home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
CD ROM Paradise Collection 4
/
CD ROM Paradise Collection 4 1995 Nov.iso
/
program
/
qbgps240.zip
/
GPS.DOC
< prev
next >
Wrap
Text File
|
1995-01-11
|
132KB
|
2,571 lines
Documentation for
┌───────────────────────────────────────────────────┐
│ GPS (General Purpose Subroutines) Library <v248> │
│ (c) Garry Spencer / Spencer Technologies │
│ P.O. Box 34OO9 Memphis, TN 38184-OOO9 │
└───────────────────────────────────────────────────┘
┌───────────────┬─────────────────────────────────┐
│ Number of │ │
│ Functions in │ │
├───────┬───────┤ │
│GPS.LIB│GPS.QLB│ Function Group │
├───────┼───────┼─────────────────────────────────┤
│ 24 │ 24 │ Date / Time │
│ 18 │ 18 │ DOS (Handle-Based) │
│ 13 │ 13 │ File / Directory │
│ 8 │ 8 │ Joystick │
│ 25 │ 25 │ Keyboard │
│ 27 │ 27 │ Memory │
│ 17 │ 17 │ Mouse │
│ 22 │ 22 │ Numeric │
│ 22 │ 22 │ Screen (ANSI - text mode only) │
│ 32 │ 24 * │ Screen (VIDEO- text mode only) │
│ 36 │ 36 │ String │
│ 4 │ 4 │ System / Miscellaneous │
├───────┼───────┼─────────────────────────────────┤
│ 248 │ 24O │ Total Number of Functions │
└───────┴───────┴─────────────────────────────────┘
* Note that the GPS.QLB quick-library does NOT support the following 8 routines:
ColorPDQ, ColorQB, SetColorPDQ, SetColorQB, SetVideoSegPDQ, SetVideoSegQB,
VideoSegPDQ and VideoSegQB.
Warranty: None expressed or implied.
The routines in this library have been thoroughly tested with
Quick-BASIC version 4.5, HOWEVER Spencer Technologies and/or any employees
of the company are not liable for the use or misuse of this software.
The registered version of this software package is protected under the
copyright laws of the United States of America. It must not be copied,
transmitted or duplicated in any way. It is to be used only by the purchaser.
INSTRUCTIONS FOR USING THE GPS LIBRARY WITH QUICK-BASIC
The GPS library was designed solely for use with programs written in
Quick-BASIC. Some of the routines may work with BASIC PDS or Visual-BASIC
for DOS, however the testing of these routines was limited to programs
written in Quick-BASIC version 4.5 ONLY. In some of the functions, CALLs
were made to Quick-BASIC's internal routines such as B$ASSN etc.
The GPS library was also tested with the PDQ (BASIC replacement) library from
Crescent Software, 11 Bailey Ave., Ridgefield, CT O6877 (2O3-438-53OO).
Their PDQ library replaces the BCOM45.LIB (and QB.LIB) libraries and creates
.EXE files about one-half the size of normal Quick-BASIC executable files.
Be sure to make a backup copy of the enclosed diskette (for your own use only).
Note that capital O is used throughout this documentation in place of the
slashed-zero (0).
The GPS.QLB quick-library is designed to be used inside the Quick-BASIC
editor/environment (e.g. QB progname /L GPS).
Note that the GPS.QLB quick-library does NOT support the following 8 routines:
ColorPDQ, ColorQB, SetColorPDQ, SetColorQB, SetVideoSegPDQ, SetVideoSegQB,
VideoSegPDQ and VideoSegQB.
The GPS.LIB library is designed to be used ONLY from the DOS command line.
Note that each function and/or subroutine in the GPS.LIB library MUST be
declared before it can be used. There is a file named GPS.BI which is
included on the enclosed diskette. This file contains the correct DECLARE
statement for each routine in GPS.LIB. To allow your programs to use this
file, place the following statement in your source code (before any executable
statements).
'$Include: '\QB45\GPS.BI'
Note that the single-quotes (') must be included as part of the statement.
The \QB45 directory can be replaced with the appropriate directory name
in which the GPS.BI file resides. If you wish to copy the individual DECLARE
statements from the GPS.BI file to your source code, you should be extremely
careful to use the BYVAL and SEG keywords wherever they appear. The under-
score symbol (_) is used at the end of a line in Quick-BASIC to allow the
program line to be continued on the next physical line in the file. Be sure
to copy the entire DECLARE statement including continuation lines.
To compile your program, type the following:
BC progname/O;
if you are not using ON ERROR GOTO/RESUME statements
BC progname/O/E/X;
if you are using ON ERROR GOTO/RESUME statements
To link your program into an .EXE executable file, type:
LINK/EX progname,,nul,\QB45\GPS;
if you are linking with Quick-BASIC's BCOM45.LIB
(assuming that the GPS.LIB file is in the \QB45 directory. You should
obviously use the directory name in which the GPS.LIB file is located.)
LINK/EX/NOD/NOE progname,,nul,\PDQ\PDQ \QB45\GPS;
if you are using the PDQ.LIB library from Crescent Software
(assuming that PDQ.LIB is located in the \PDQ directory)
SPECIAL PROGRAMMING CONSIDERATIONS
Many of the GPS functions use 16-bit (2-byte) integer values as operands or to
return information to your program. Quick-BASIC's 2-byte integer variables
(such as X%) use 16-bit signed values which have a range of -32768 to +32767.
A 16-bit UNsigned integer can actually represent numbers in the range of O to
+65535. There is a problem when using (%) type variables to represent numbers
between +32768 and +65535. For example, the number used to represent the
segment address of the text-mode memory area for a color monitor is 471O4.
This number is obviously too large to be used in: X% = 471O4%. You must
therefore, use another method of assigning the value 471O4 to the X% variable.
The methods normally used for this purpose include representing these large
values as hexadecimal numbers or as NEGATIVE numbers.
To use hexadecimal: 471O4 is the same as B8OO (hex)
X% = &HB8OO
Note: Many scientific calculators can convert between decimal and hexadecimal.
To convert large numbers in the range (+32768 to +65535) to negative values use:
NegativeValue = LargeValue - 65536
For example, 471O4 - 65536 = -18432
X% = -18432% is the same as X% = &HB8OO
Note: 65536 is too large to be used as a 2-byte integer in Quick-BASIC programs.
If the conversion is to be calculated inside a program, use 65536& to
allow the compiler to treat 65536 as a 4-byte (long) integer.
To convert back from a negative value to a large positive value, use:
LargeValue = NegValue + 65536 (ex. -18432 + 65536 = 471O4)
The reason for the problem lies in the way Quick-BASIC uses a 16-bit (2-byte)
number to represent signed values. The following diagram shows a 16-bit binary
number. Each N represents a BIT which stands for (BInary-digiT). Each bit
is either a one (1) or a zero (O) and is a power of two.
16384 4O96 1O24 256 64 16 4 1
N N N N N N N N N N N N N N N N
32768 8192 2O48 512 128 32 8 2
As you can see, if all bits are ON (i.e. equal to 1) the number would be:
1111111111111111 binary = FFFF (hexadecimal)
--or--
1+2+4+8+16+32+64+128+256+512+1O24+2O48+4O96+8192+16384+32768 = 65535 decimal
HOWEVER, Quick-BASIC (and the 8Ox86) has designated the most-significant
(leftmost) bit as the SIGN bit, so that it no longer means 32768 in signed
2-byte integers.
If the sign bit is zero (O), the signed number is considered to be positive,
therefore:
O111111111111111 binary = 7FFF (hexadecimal)
--or--
1+2+4+8+16+32+64+128+256+512+1O24+2O48+4O96+8192+16384 = 32767 decimal
If the sign bit is one (1), the signed number is considered to be negative,
and is stored in 2s complement form. For example,
1111111111111111 = FFFF (hexadecimal)
the sign bit is a one (1) therefore the number is negative and in 2s complement
form. The number shown is -1 (in decimal). Convert from/to 2s complement form
by complementing (inverting) all bits (1s complement), then add 1 to the result.
SPECIAL PROGRAMMING CONSIDERATIONS (Continued)
Segmented Memory Addressing
Some of the microprocessors used in IBM-compatible computers (8O386+) can
address all of the available memory space in a linear manner. The earlier
processors (8O88, 8O86 etc) were designed to address memory in segments.
The latest processors (Pentium etc.) can still be used to address memory which
has been laid out in segments, therefore it is necessary to mention this
method of memory access in this documentation.
A typical segmented memory address has the following form:
pppp:oooo where pppp is the paragraph (segment) and oooo is the offset
within that segment. Note that both numbers are shown in
4-digit hexadecimal form.
The actual memory address can be found by multiplying the paragraph by
16 (1O hex) and then adding the offset to that number. For example,
segmented memory address 1742:4982 (hexadecimal) means that the paragraph is
1742 (hex) and the offset is 4982 (hex). Calculating the actual address,
(1742 x 1O = 1742O) + 4982 = 1BDA2 (the actual address in hexadecimal)
It is intuitively obvious to even the most casual observer, that each
paragraph can only start on a memory location which is evenly divisible
by 16. From that starting address, it is possible to address up to 64k
(O to 65535) different memory locations (byte-wide). The accepted
terminology, used in most literature, dictates that a paragraph of memory is
16 bytes long and that a segment of memory can be up to 64k (65536) bytes
in length. Sometimes the terms paragraph and segment are used to represent
the same thing, but it is usually apparent which meaning these terms have in
context.
To find the actual memory location of a variable, the Quick-BASIC commands
VARSEG and VARPTR can be used. VARSEG finds the segment in which the variable
resides and VARPTR finds the offset (pointer) from the start of that segment.
Note that Quick-BASIC's default data segment is called DGROUP.
A% = 1
MemSeg% = VARSEG ( A% ) 'find the segment in which A% resides
MemPtr% = VARPTR ( A% ) 'find the offset (pointer)
In this example, the variable (A%) is located at segment MemSeg% and at
offset (pointer) MemPtr%. Please note that for each memory location, there
are several combinations of segment and offset addresses which could point to
that actual memory location. For example,
2415:OO11 is the same as 2416:OOO1 (in hexadecimal). It is possible to
minimize the offset (pointer) by adding 1 to the segment while subtracting
16 (1O hex) from the offset. If this is done repeatedly, the offset can be
reduced to the range (O to 15) or (O to F hex). This is exactly what the
GPS library function MinimizePtr does. The function VarSegPtr also returns
a minimized offset/segment combination for a given variable. If your program
will be copying large blocks of memory, it would be best to minimize the
offset (pointer) before using GPS functions like MemCopy etc. This will
prevent a problem with overflow on the (DS:SI and/or ES:DI) internal registers.
SPECIAL PROGRAMMING CONSIDERATIONS (Continued)
Variable-Length Strings vs Fixed-Length Strings
Many of the routines in the GPS.LIB library require a string as an operand.
DO NOT use a fixed-length string for ANY of these operands (arguments). The
reason for this is that Quick-BASIC stores these two string types differently.
A fixed-length string is basically a block of memory which can either reside
in DGROUP (default data segment) or in the far heap (outside DGROUP). A
Quick-BASIC variable-length string, such as X$, must reside in DGROUP. In
order to keep the assembly language code size small, it was assumed that all
string operands were variable-length ($) string types. A quoted string, like
"text string" is also stored (as a constant) in variable-length string format,
so that this type can also be used as an operand. Note that some routines
actually change the operand string directly (e.g. UpperCase). For these
routines you should NOT use a quoted string constant, such as "Text".
An example of each string type is given below:
DIM TXT AS STRING*5O
TXT is a fixed-length string and should NEVER be used as a string operand.
The statement: Call UpperCase ( TXT ) would therefore be illegal.
"The quick brown fox" is a quoted string which is stored like a variable-length
string and can be used as a string operand for MOST but not all routines. This
string type may NOT be used in routines which change the string directly,
such as ChgMid, LowerCase, Replace, and UpperCase.
TextString$ is a variable-length string which can be used as an operand in ANY
of the GPS.LIB routines.
Note that a fixed-length string can be used to receive the return value of a
string function. For example, the following program code is correct:
DIM TXT AS STRING*34
TXT=FindFile$ ( O, "*.BAS", 7)
SPECIAL PROGRAMMING CONSIDERATIONS (Continued)
A Quick-BASIC variable-length string is stored in the following manner:
┌──────┬──────┬──────┬──────┐
│ Length │ Location │
└──────┴──────┴──────┴──────┘
└─────────────┬─────────────┘
│
This is a 4-byte string descriptor for a variable-length string.
The string descriptor is made up of 2 bytes for the string length and 2 bytes
for the location (offset within the DGROUP segment) of the first byte of the
actual string data.
┌──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬──────┬─∙∙∙∙∙
│ Back Pointer│ Actual string data would be placed here .....
└──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴──────┴─∙∙∙∙∙
The back pointer (which ALWAYS immediately precedes the actual string data
in memory) points to the memory location of the first byte of the string
descriptor (shown above). The back pointer is used by Quick-BASIC to allow
clean-up of the string data area. Quick-BASIC examines the back pointers and
each back pointer allows Quick-BASIC to find the string descriptor belonging
to the back pointer's accompanying string data. If the string descriptor
(pointed to by a back pointer) no longer points to the actual string data, then
Quick-BASIC knows that the memory block occupied by the string data can be
reclaimed for other strings etc.
The 64k-byte DGROUP segment, which holds the string descriptor, the back pointer
and the actual string data, can be determined by the following statement.
DGROUP% = VARSEG(TextString$)
The location of the first byte of the string descriptor is found as follows:
StrDesc% = VARPTR(TextString$)
The location of the first byte of the actual string data is found by:
StrData% = SADD(TextString$)
The following program code shows how to access each part of the string
(TextString$).
DGROUP% = VARSEG(TextString$) 'finds the default data segment DGROUP
DEF SEG = DGROUP% 'make PEEKs/POKEs use DGROUP segment
StrDesc% = VARPTR(TextString$) 'finds address of 1st byte of string descriptor
Length% = 256% * PEEK(StrDesc%+1) + PEEK(StrDesc%)
StrData% = SADD(TextString$) 'finds address of 1st byte of actual string data
StrData% = 256% * PEEK(StrDesc%+3) + PEEK(StrDesc%+2) 'another way to find it
BackPtr% = StrDesc% 'the same for an active string (address of descriptor)
BackPtr% = 256% * PEEK(StrData%-1) + PEEK(StrData%-2) 'another way to find it
Note: The back pointer itself (BackPtr%) holds the ADDRESS (within DGROUP) of
the first byte of the string descriptor.
SPECIAL PROGRAMMING CONSIDERATIONS (Continued)
Text Screen Color Attribute Byte
The screen subroutines and functions, in the GPS library, are to be used in
text-mode only (SCREEN O). These routines use direct video memory writes to
update the screen. You will notice that some of these routines require a
color attribute byte operand.
The format for this byte is as follows (shown as an 8-bit binary number):
Blink Bit High-Intensity (Bright) Bit
│ │
┌─┴─┐ ┌─┴─┐
N N N N N N N N
└───────┬───────┘ └──────────┬──────────┘
│ │
Background Color Foreground color
( O to 7 ) ( O to 7 for normal )
( 8 to 15 for bright )
The basic colors are:
O = black 8 = dark gray
1 = blue 9 = bright blue
2 = green 1O = bright green
3 = cyan 11 = bright cyan
4 = red 12 = bright red
5 = magenta (purple) 13 = bright magenta (purple)
6 = brown 14 = bright yellow
7 = white / gray 15 = bright white
Note: The Quick-BASIC command:
COLOR foreground,background
uses numbers 16 to 31 as blinking foreground colors. (16 + foreground)
You can use the GPS library function ColorAttr% to calculate the value of the
attribute byte. If Foreground% represents Quick-BASIC's foreground color
(O to 31) and Background% represents the background color (O to 7), then the
following line of code will calculate the correct color attribute byte.
ColorAttributeByte% = ColorAttr% ( Foreground% , Background% )
If the value of a color attribute byte is known, and you wish to separate
it into separate foreground and background colors, use the following command:
Call AttrColor ( ColorAttributeByte% , Foreground% , Background% )
-----or the alternate form of calling a subroutine-----
AttrColor ColorAttributeByte% , Foreground% , Background%
SPECIAL PROGRAMMING CONSIDERATIONS (Continued)
Special Note:
Quick-BASIC version 4.5 supports the use of alphanumeric labels. It is no
longer necessary to use line numbers. This is good news for programmers,
however it can cause a minor problem when using external subroutines such as
the ones in the GPS library. Here is the problem:
There are two ways to call a subroutine in Quick-BASIC. The first method is
to use the CALL keyword and enclose the operands (if any) in parentheses.
For example,
Call NumLockOff
Call AttrColor(Attr%,Fore%,Back%)
The second method of calling these subroutines is to simply use the name of the
subroutine followed by the operands (no parentheses).
NumLockOff
AttrColor Attr%,Fore%,Back%
Both of these methods work, but since Quick-BASIC allows multiple statements
per line by using a colon (:) and it also uses the colon (:) at the end of an
alphanumeric label, Quick-BASIC can sometimes get confused if you use the
second method of calling a subroutine (with no operands) and try to place
another statement on the same line using a colon (:). For example,
NumLockOff : Call AttrColor(Attr%,Fore%,Back%)
Quick-BASIC will think that NumLockOff is a label even though there is a
space between it and the colon (:). This is a problem even when the
subroutine has been previously declared. You should either put NumLockOff
on a separate line or use the Call NumLockOff format. This is a minor problem
that only occurs if the subroutine has no operands.
Special Note: In an attempt to keep code size small, error checking on
operands (e.g. screen row and column) was kept to a minimum. If the
documentation shows the limits on a particular function, your calling program
should make sure that no out-of-bounds operands are supplied to the functions.
SPECIAL PROGRAMMING CONSIDERATIONS (Continued)
USING THE ALIAS KEYWORD IN A DECLARE STATEMENT
The ALIAS keyword allows you to substitute the name of one of Quick-BASIC's
internal functions/subroutines in the place of your routine. This is necessary
in most cases because many of Quick-BASIC's internal routines use the
($) dollar-sign or the (_) underscore in the function name.
For example, pass an an ERRORLEVEL to DOS on exit from your program.
The DECLARE tells Quick-BASIC to substitute _exit for the EndERRLevel statement.
'------------------------------------------------------------------------------
'In Quick-BASIC use this:
DECLARE SUB EndERRLevel ALIAS "_exit" (BYVAL ErrorLevel%)
EndERRLevel 15 'this would end your program and also pass the number 15
'to DOS as the ERRORLEVEL variable which could then be
'tested in a batch file with the IF ERRORLEVEL statement
'Note: This particular routine (_exit) will only work when compiled to an
.EXE file from the command line.
'------------------------------------------------------------------------------
'------------------------------------------------------------------------------
'In PDQ you MUST use PDQ's ErrLevel Statement (no alias)
DECLARE SUB ErrLevel (ErrorLevel%)
EndLevel 15 'this would end your program and also pass the number 15
'to DOS as the ERRORLEVEL variable which could then be
'tested in a batch file with the IF ERRORLEVEL statement
'------------------------------------------------------------------------------
Some additional examples are shown below:
DECLARE SUB FileRead ALIAS "B$GET4" (BYVAL FileNum%, BYVAL FilePosition&, _
BYVAL MemSegment%, BYVAL MemOffset%, _
BYVAL NumberOfBytes%)
DECLARE SUB FileWrite ALIAS "B$PUT4" (BYVAL FileNum%, BYVAL FilePosition&, _
BYVAL MemSegment%, BYVAL MemOffset%, _
BYVAL NumberOfBytes%)
OPEN "Test.Dat" FOR BINARY AS BASICFileNumber%
FileRead BASICFileNumber%,FilePosition&,MemSegment%,MemOffset%,NumberOfBytes%)
FileWrite BASICFileNumber%,FilePosition&,MemSegment%,MemOffset%,NumberOfBytes%)
These two routines will read-from/write-to a file opened in BINARY mode.
Data is transferred directly between the file and memory (segment:offset).
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATE / TIME FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
FUNCTION: DayOfWeek% (AnyDate$)
Returns the day of the week (O=Sunday ... 6=Saturday) for the specified date
in MM-DD-YYYY form. Note: MM is month (1 to 12), DD is day (1 to 31) and YYYY
is the year (198O to 21O7). The date must be on or after O1-O1-198O. If an
incorrect date is specified, the program will be halted by "Illegal Function
Call" caused by BASIC's (B$SDAT routine).
example: Day%=DayOfWeek%("12-31-1999")
FUNCTION: DayStr$ (WkDay%)
Returns a string containing the day of the week specified by WkDay% (O to 6).
example: A$=DayStr$(O) 'A$ would be "Sunday" (note the mixed case)
A$=DayStr$(6) 'A$ would be "Saturday"
FUNCTION: DayWeek% (Mon%, Day%, Year%)
Returns the day of the week (O=Sunday ... 6=Saturday) for the specified date.
Note: Do not use MONTH% as a variable. The year must be in the range 198O to
21O7. If an incorrect date is specified, the function will return -1 (error).
example: DWeek% = DayWeek%(12,31,1999)
Note: If you need to use a year outside 198O to 21O7, then use the WeekDay%
function.
FUNCTION: EventDone%
Checks the status of the last EventSet subroutine call. If EventDone% is zero,
it means the event timer is still running. If it is equal to -1, it signals
that the timer has finished its timed interval. (see EventSet subroutine)
SUBROUTINE: EventSet Microseconds&
Starts the event timer with a value in microseconds. The status of the event
can be checked using the EventDone% function.
For example: (note: 1 microsecond = 1 millionth of a second)
EventSet 1OOOOO& '1OOOOO microseconds is the same as .1 sec
While Not EventDone%
'your statements here will continuously execute for .1 seconds
Wend
SUBROUTINE: EventWait Microseconds&
Starts the event timer with a value in microseconds. This routine differs from
EventSet in that EventWait does not return to the calling program until the
event timer interval has elapsed.
example: EventWait 5OOOOO& 'wait here for one-half second
SUBROUTINE: GetDate Mon%, Day%, Year%, DWeek%
Returns the month, day, year and day-of-week into the specified variables.
Notes: For DWeek% O=Sunday ... 6=Saturday
Do not use MONTH% as a variable.
example: GetDate MM%,DD%,YY%,DWk%
SUBROUTINE: GetTime Hrs%, Min%, Sec%, HSec%
Returns the hours (O to 23), minutes, seconds and hundredths-of-seconds into
the specified variables. Note: The time is only updated 18.2 times per second.
example: GetTime HH%,MM%,SS%,S1OO%
SUBROUTINE: Hibernate TickVal%
Causes program execution to pause for a length of time equal to the specified
number of timer ticks. Key presses are ignored during the paused state.
Note: There are approximately 18.2 timer ticks in one second.
example: Hibernate 91% 'pause for 5 seconds
FUNCTION: LongDate$ (Date2Byte$)
Expands a previously compressed 2-byte date string into a 1O-byte date string
with the form MM-DD-YYYY (month-day-year). This function should only be used
with the ShortDate$ function. NO error checking is performed on the date!
FUNCTION: LongTime$(TwoByte$)
Expands a previously compressed 2-byte time string into a 5-byte time string
with the form HH:MM (24-hour format). This function should only be used with
the ShortTime$ function. NO error checking is performed on the time!
FUNCTION: MonthStr$ (MonthVal%)
Returns a string containing the month name specified by MonthVal% (1 to 12).
example: A$=MonthStr$(1) 'A$ would be "January" (note the mixed case)
A$=MonthStr$(12) 'A$ would be "December"
FUNCTION: SetDate% (Mon%, Day%, Year%)
Sets the current date to the specified month, day and year. Note: Do not
use MONTH% as a variable. The year must be in the range of 198O to 21O7.
This function returns zero if the specified date is valid, otherwise it
returns -1 (error).
example: X%=SetDate%(12,31,1999) 'sets date to 12-31-1999
'X%=O if o.k. X%=-1 if error
FUNCTION: SetTime% (Hrs%, Min%, Sec%, HSec%)
Sets the current time to the specified hours (O to 23), minutes, seconds and
hundredths-of-seconds. This function returns zero if the specified time is
valid, otherwise it returns -1 (error).
example: X%=SetTime%(23,45,33,25) 'sets time to 23:45:33.25
'X%=O if o.k. X%=-1 if error
FUNCTION: ShortDate$ (AnyDate$)
Compresses the given 1O-byte date string (MM-DD-YYYY form) into a 2-byte string
which can then be stored in a file etc. The 2-byte resultant string can be
used in a chronological sort routine. This function should be used with
with the LongDate$ function. NO error checking is performed on the date.
example: SDate$=ShortDate$("12-31-1999")
LDate$=LongDate$(SDate$)
FUNCTION: ShortTime$ (Time24$)
Compresses the given 5-byte time string (HH:MM 24-hour format) into a 2-byte
string which can then be stored in a file etc. The 2-byte resultant string
can be used in a chronological sort routine. This function should be used
with the LongTime$ function. NO error checking is performed on the time.
example: STime$=ShortTime$("23:59")
LTime$=LongTime$(STime$)
FUNCTION: Snooze% (TickVal%)
Causes program execution to pause for a length of time equal to the specified
number of timer ticks or until a key is pressed. This function has a return
value equal to the keycode (if any) used to prematurely end the delay. See the
keycode table in the appendix. Note: There are approximately 18.2 timer ticks
in one second.
example: X%=Snooze%(91%) 'pause for 5 seconds or until a key is pressed
FUNCTION: TickTime$ (TickValue&)
This function converts the specified number of timer ticks (TickValue&) into
an 8-byte time string in HH:MM:SS form. (note: HH = OO to 23)
There are approximately 18.2 timer ticks in one second and approximately
1O92 ticks in one minute. The maximum number of ticks in one day is 1573O39.
example1: T$=TickTime$(Timr&) 'uses Timr& function and would return the same
'string as BASIC's TIME$ function.
example2: TLimit&= (15& * 1O92&) 'time limit is 15 minutes
TimerReset 3 'reset timer#3
Temp: TRemain& = TLimit& - TimerRead&(3) 'calculate time remaining
If TRemain& <= O GoTo Quit
Locate 1,1 : Print TickTime$(TRemain&) 'print countdown time
GoTo Temp
Quit: 'continue program here after time has expired
FUNCTION: TimerRead& (TimerNumber%)
SUBROUTINE: TimerReset TimerNumber%
TimerRead& returns the number of timer ticks since the specified TimerNumber%
was reset (using the TimerReset subroutine). The TimerNumber% should be in
the range (O to 15). If the TimerReset subroutine is called, with a
TimerNumber% outside the range (O to 15), then ALL 16 timers (O to 15) will be
reset to zero. There are approximately 18.2 timer ticks in one second.
example: TimerReset -1 'reset ALL 16 timers to zero
TimerReset 16 'reset ALL 16 timers to zero
TimerReset O 'reset only timer number O to zero
TimerReset 15 'reset only timer number 15 to zero
TMRO&= TimerRead&(O) 'TMRO& set to number of ticks since timer O was reset
TMR15&=TimerRead&(15) 'TMR15& set to number of ticks since timer 15 was reset
Note: Attempting to read outside the range (O to 15) will return unpredictable
values. These routines correctly handle the timer tick "roll-over" at
midnight, but each timer will only be valid for up to 24 hours after it
is reset to zero.
FUNCTION: TmrRd& ( TimerVariable&)
SUBROUTINE: TmrRst TimerVariable&
These routines are basically the same as the TimerRead& and TimerReset
routines, except that a long-integer variable is used to store the timer value
instead of using an internal storage area. This allows an essentially
unlimited number of timers to be used.
example: TmrRst TimerVar&
While TmrRd&(TimerVar&)<1OO : Wend 'wait here for 1OO timer ticks
FUNCTION: Timr&
Returns the number of timer ticks since midnight. Note: There are
approximately 18.2 timer ticks in one second.
example: Ticks& = Timr& 'this returns a long integer
FUNCTION: WeekDay% (Mon%, Day%, Year%)
This function is identical to the DayWeek% function except that it accepts
any year in the range (1582 A.D. to 245O A.D.). The reason that these two
functions (DayWeek% and WeekDay%) are both included in this library, is that
the WeekDay% is a bit larger than DayWeek% and should only be used when a year
outside the 198O to 21O7 range is to be specified. This function returns
O=Sunday...6=Saturday, and it returns -1 if an error occurs (i.e. illegal date).
example: A%=WeekDay%(7,4,1776) 'A% is the day of the week on which the
'Declaration of Independence was signed
'on July 4, 1776.
┌─────────────────────────────────────────────────────────────────────────────┐
│ DOS (Handle-Based) FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
The routines in this section use the standard DOS services to access files.
When a file is opened, using the DOSOpen routine, DOS assigns a unique "handle"
to that file. Note: This handle number is --NOT-- the same thing as BASIC's file
number! Your program must keep track of the handle number after a file is
opened.
The DOSRtnErr% function must be DECLAREd in your program
(or '$include: 'gps.bi') because it is the only way to determine if an error
occurred during execution of any of the GPS library DOS routines. Note: ALL of
the GPS library DOS routines modify the DOSRtnErr% value (except, of course,
the DOSRtnErr% routine itself).
SUBROUTINE: DOSClose Handle%
This routine closes the file belonging to the specified handle.
ex: DOSOpen "Temp.Fil",O,1,Handle%
DOSClose Handle%
SUBROUTINE: DOSDel FileName$
This routine deletes the specified file. Note that this routine uses the
actual filename instead of a handle.
ex: DOSDel "Temp.Fil"
FUNCTION: DOSFAttr% (FileName$)
Returns the DOS File Attribute byte value for the specified file. The bit
values of this byte are as follows:
Bit O - Binary Value= 1 - Read_Only File
Bit 1 - Binary Value= 2 - Hidden File
Bit 2 - Binary Value= 4 - System File
Bit 3 - Binary Value= 8 - Volume Name
Bit 4 - Binary Value= 16 - Directory Name
Bit 5 - Binary Value= 32 - Archive Bit
Bit 6 - Binary Value= 64 - <reserved>
Bit 7 - Binary Value= 128 - <reserved>
Note that this function uses the actual filename instead of a handle.
ex: Attributes% = DOSFAttr% ("Temp.Fil") 'get the attributes for a file
SUBROUTINE: DOSFAttrSet FileName$, AttributeByte%
Sets the DOS File Attribute Byte for the specified file using the value of
AttributeByte%. See the DOSFAttr% function for a description of this byte.
Note that this subroutine uses the actual filename instead of a handle.
ex: Attributes% = DOSFAttr% ("Temp.Fil")
DOSFAttrSet "Temp.Fil", (Attributes% OR 1) 'make the file read-only
SUBROUTINE: DOSFDateGet Handle%, Mon%, Day%, Year%, Hr%, Min%, Sec%
This routine retrieves the date and time for the file whose handle is specified.
Note: The 24-hour system is used for Hr% (i.e. OO to 23).
ex: DOSOpen "Temp.Fil",O,1,Handle%
DOSFDateGet Handle%,Month%,Day%,Year%,Hour%,Minute%,Second%
DOSClose Handle%
SUBROUTINE: DOSFDateSet Handle%, Mon%, Day%, Year%, Hr%, Min%, Sec%
This routine sets the date and time for the file whose handle is specified.
Note: The 24-hour system is used for Hr% (i.e. OO to 23). The seconds must be
an even number. The year must be 198O or later.
ex: DOSOpen "Temp.Fil",O,1,Handle%
DOSFDateGet Handle%,Month%,Day%,Year%,Hour%,Minute%,Second%
DOSFDateSet Handle%,Month%,Day%,Year%,O,O,O 'set file time to midnight OO:OO
DOSClose Handle%
'Note: The DOSFDateGet routine was used first because it was necessary
' in order to preserve the month, day and year.
FUNCTION: DOSFPtr& (Handle%)
This routine retrieves the file pointer for the file whose handle is specified.
The file pointer is the place in the file where the next file read or write
would occur. Note that the beginning of the file is at pointer value=O.
ex: FilePointer& = DOSFPtr&(Handle%) : Print FilePointer&
SUBROUTINE: DOSFPtrMove Handle%, PtrMovement&
This routine moves the file pointer by the number of bytes specified by
PtrMovement& for the file whose handle is specified. If PtrMovement& is positive
then the movement is forward. If PtrMovement& is negative then the movement is
backwards. Note that the beginning of the file is at pointer value=O.
ex: DOSFPtrMove Handle%, 16 'move file pointer forward by 16 bytes
DOSFPtrMove Handle%,-12 'move file pointer backwards by 12 bytes
SUBROUTINE: DOSFPtrSet Handle%, NewPtr&
This routine sets the file pointer to the position specified by NewPtr& for
the file whose handle is specified. Note that the beginning of the file is at
pointer value=O.
ex: DOSFPtrSet Handle%,O 'set the pointer to the beginning of the file
FileSize&=DOSFSize&(Handle%)
DOSFPtrSet Handle%,FileSize& 'set the pointer to the end of the file
'for append mode operation
FUNCTION: DOSFSize& (Handle%)
Returns the file size of the file whose handle is specified.
ex: DOSOpen "Temp.Fil",O,1,Handle%
FileSize& = DOSFSize&(Handle%)
DOSClose Handle%
SUBROUTINE: DOSOpen FileName$, ReadWrite%, InitPtr%, Handle%
Opens the specified file and assigns its handle to the Handle% variable.
The ReadWrite% value should be specified as O=read-only, 1=write-only and
2=read-write. The InitPtr% should be specified to instruct DOS where the
DOS file pointer should be positioned for this file, O=truncate file to
zero length (only if ReadWrite%>O), 1=point to beginning of file and
2=point to end of file.
ex: DOSOpen "Temp.Fil",O,1,Handle%
'opens the file as read-only and points to the beginning of the file
'and assigns its handle to the Handle% variable
SUBROUTINE: DOSRdMem Handle%, MSeg%, MPtr%, NBytes%
SUBROUTINE: DOSRdStr Handle%, Text$, NBytes%
SUBROUTINE: DOSRdVar Handle%, AnyVariable, NBytes%
These routines read data from the file, whose handle is specified, starting at
the current position of the file pointer. The first form (DOSRdMem) reads the
specified number of bytes, from the file, into the segmented memory address
MSeg%:MPtr%. The second form (DOSRdStr) reads the specified number of bytes,
from the file, into a variable-length string variable Text$. The third form
(DOSRdVar) reads the specified number of bytes, from the file, into a normal
variable or a TYPE variable.
ex: DOSRdMem Handle%,&hB8OO,O,4OOO 'reads a 4OOO-byte screen image into the
'color (text) video memory segment from file
DOSRdStr Handle%,XYZ$,123 'reads 123 bytes into the XYZ$ string from file
DOSRdVar Handle%,A%(O),9O 'reads 45 values (2 bytes each) into integer
'array A%() from file
'note: array must first be dimensioned
FUNCTION: DOSRtnErr%
Returns zero if the last GPS library DOS routine did not result in an error,
otherwise the actual DOS error number is returned.
ex: DOSOpen "FileName.Ext",O,1,Handle%
ErrorInDOS% = DOSRtnErr%
If ErrorInDOS%<>O Then Print "DOS Error Number ";ErrorInDOS% : Goto Halt
SUBROUTINE: DOSWrtMem Handle%, MSeg%, MPtr%, NBytes%
SUBROUTINE: DOSWrtStr Handle%, Text$
SUBROUTINE: DOSWrtVar Handle%, AnyVariable, NBytes%
These routines write data to the file, whose handle is specified, starting at
the current position of the file pointer. The first form (DOSWrtMem) writes the
specified number of bytes, to the file, from the segmented memory address
MSeg%:MPtr%. The second form (DOSWrtStr) writes the contents of the
variable-length string Text$ to the file. The third form (DOSWrtVar) writes
the specified number of bytes, to the file, from a normal variable or a TYPE
variable.
ex: DOSWrtMem Handle%,&hB8OO,O,4OOO 'writes a 4OOO-byte screen image from the
'color (text) video memory segment to file
DOSWrtStr Handle%,XYZ$ 'writes the XYZ$ string to the file (no cr-lf added)
DOSWrtVar Handle%,A%(O),9O 'writes 45 values (2 bytes each) from integer
'array A%() to file
'note: array must first be dimensioned
┌─────────────────────────────────────────────────────────────────────────────┐
│ FILE / DIRECTORY FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
SUBROUTINE: ChgDir NewDir$
Changes the default directory to the one specified. If the drive is different
from the current drive, it is also changed. Note: BASIC's CHDIR command will
not change the default drive.
example: ChgDir "A:" 'changes ONLY the drive
ChgDir "A:\" 'changes the drive and directory
FUNCTION: CurrentDir$
Returns the current default directory including drive.
example: ChgDir "C:\"
A$=CurrentDir$
ChgDir "\TEMP"
B$=CurrentDir$
Print A$,B$
result: C:\ C:\TEMP
FUNCTION: DirExist% (FileName$)
Returns -1 if the specified directory exists and returns zero (O) if it doesn't.
Note: If a critical error occurs (drive door open etc.) the critical error
message (Abort - Retry - Fail) will still appear on the screen.
Exist%=DirExist%("C:\TEMP")
FUNCTION: DriveDir$ (Drive%)
Returns the current default directory on the specified drive:
O=current drive 1=A: 2=B: 3=C: etc.
example: A$=DriveDir$(3)
print A$
result: C:\TEMP
FUNCTION: FileExist% (FileName$)
Returns -1 if the specified file exists and returns zero (O) if it doesn't.
Note: If a critical error occurs (drive door open etc.) the critical error
message (Abort - Retry - Fail) will still appear on the screen.
Exist%=FileExist%("C:\TEMP\MISC.DAT")
SUBROUTINE: FileToMem FileNum%,MemSeg%,MemAdr%,NumBytes%
Copies the specified number of bytes (NumBytes%) from a file (at the current
file pointer location) directly into memory at paragraph (MemSeg%) and offset
(MemAdr%). The FileNum% is BASIC's file number (not the file handle). The file
must already be opened in Binary Access Read mode.
example:
'Copy 4OOO bytes from the beginning of a file to video memory
Open "Temp.SCN" for Binary Access Read as #1
FileToMem 1,&HB8OO,O,4OOO : Close#1
SUBROUTINE: FileToVar FileNum%,Variable,VariableSize%
Copies the specified number of bytes (VariableSize%) from a file (at the current
file pointer location) directly into memory at the location of the specified
Variable. The FileNum% is BASIC's file number (not the file handle). The file
must already be opened in Binary Access Read mode. This routine is handy for
reading from a file directly into a TYPE variable.
ex: TYPE NewVar:First as Integer:Second as Integer:END TYPE:Dim Temp as NewVar
Open "Temp.TMP" for Binary Access Read as #1
FileToVar 1,Temp.First,4 : Close#1 'reads both 2-byte integers
FUNCTION: FindFile$ (First%,Search$,AttrMask%)
Returns a 34-byte directory string containing information about the file(s)
specified in the Search$ string. The First% operand must be zero (O) for the
first function call to this routine and non-zero for all subsequent calls
(with the same Search$ and AttrMask% specification). If a different search
criteria specification is given (later in the program) then First% must again
be set to zero for the first call and non-zero for subsequent calls. This is
due to the fact that the DOS call used here must set up the DTA area on the
first call. Additional calls, using a non-zero First% value, will use the DTA
area previously defined. The Search$ operand can be any valid file
specification including directory names, wildcards etc. Please note that the
11-byte filename RETURNED by this function will NOT include its directory name.
The AttrMask% tells DOS which types of files to include in the search. Normal
files (non-directory, non-volume label, non-hidden etc.) are ALWAYS included
except when bit 3 (binary value 8) is set. See the example for bit meanings.
The 34-byte FindFile$ string returned by this function has the following form:
┌─filename in FILENAMEEXT form (no path/directory name returned for the file)
│ ┌─filesize in 1O-byte string form
│ │ ┌─file date in YYYYMMDD form (YYYY=year MM=month DD=day)
│ │ │ ┌─file time in HHMM (24hr) form
├─────────┐├────────┐├──────┐├──┐┌─file attribute byte
FILENAMEEXT2147483647199912312359#
FindFile$ returns a null ("") string when no more files are found.
Note: The filesize is returned as a 1O-byte string. It was possible to return
a 4-byte (compressed) value thus saving 6 bytes, however most programmers
would want to print this field directly or use it in a sort routine,
therefore it was decided to put it in printable form in the return string.
The FindFileS subroutine (on the next page) is a shortened version of
this routine.
Example: Find first file matching *.* specification
F$=FindFile$(O,"*.*",7)
FileName$=Left$(F$,8)+"."+Mid$(F$,9,3)
'FileName$ converts FILENAMEEXT form to FILENAME.EXT form
FSize$=Mid$(F$,12,1O)
'FSize$ is the file size in 1O-byte string form (handy for sorting/printing)
'could also use FSize$=Right$(Mid$(F$,12,1O),NumDigits%) to shorten string
FDate$=Mid$(F$,26,2)+"-"+Mid$(F$,28,2)+"-"+Mid$(F$,22,4)
'FDate$ converts YYYYMMDD form to MM-DD-YYYY form
Time24$=Mid$(F$,3O,2)+":"+Mid$(F$,32,2)
'Time24$ converts HHMM to HH:MM (24hr) form
FAttr%=AscMid%(F$,34)
'FAttr% uses GPS library function AscMid% to get the file attribute byte:
'bit O binary value 1 = read-only
1 2 = hidden
2 4 = system
3 8 = volume ID
4 16 = directory
SUBROUTINE: FindFileS First%,Search$,AttrMask%,TypeVariable
This subroutine is identical to the FindFile function except that a shorter
(2O-byte) string is returned INTO the specified TypeVariable. This shorter
string is useful if a large list of files (and file info) is to be stored in
memory. The following program code shows how to define and use the TypeVariable.
This routine requires more work in uncompressing the DTA-format-information
than the FindFile function does.
Type DirVar
FileName as String*8
FileExt as String*3
Attribute as String*1
FTime as Integer
FDate as Integer
FSize as Long
End Type
Dim Dir as DirVar
'---Dir is now a variable of Type DirVar
FindFileS O,"*.*",7,Dir 'for first try use First%=O
FindFileS -1,"*.*",7,Dir 'for subsequent tries use non-zero First%
The Dir.Attribute is set to ASCII 255 when no more files are found.
'after the FindFileS subroutine is executed, the following variables
'are available for use in your program:
'Dir.FileName is the filename as an 8-byte fixed-length string
'Dir.FileExt is the extension as a 3-byte fixed-length string
Name$ = RTRIM$(Dir.FileName) : Ext$ = RTRIM$(Dir.FileExt)
If Ext$<>"" Then Name$=Name$+"."+Ext$
'Dir.Attribute is a 1-byte fixed-length string representing the file's attribute
' byte (use BASIC's ASC function to get its integer value)
FileAttr% = ASC(Dir.Attribute)
'Dir.FTime is the file time as a 16-bit integer (DTA format)
' Note: Dir.Time is a SIGNED integer - be careful when sorting by time
' x x x x x x x x x x x x x x x x
' └─┬───────────────┘ └───┬─────────────────┘ └──┬──────────────┘
' Hours (O to 23) Minutes (O to 59) Seconds in 2sec intervals
FileTime% = Dir.FTime
'---or---
FileTime% = ShiftRight%(Dir.FTime,5) 'to use in sort routines
'Dir.FDate is the file date as a 16-bit integer (DTA format)
' x x x x x x x x x x x x x x x x
' └─┬───────────────────────┘ └─┬───────────┘ └─┬───────────────┘
' Year - 198O (offset) Month (1 to 12) Day (1 to 31)
FileDate% = Dir.FDate
'Dir.FSize is the file size as a 4-byte (long) integer
FileSize& = Dir.FSize
SUBROUTINE: MemToFile FileNum%,MemSeg%,MemAdr%,NumBytes%
Copies the specified number of bytes (NumBytes%) from memory at paragraph
(MemSeg%) and offset (MemAdr%) into the file (at the current file pointer
location) whose BASIC file number (FileNum%) is specified. The file must
already be opened in Binary mode. Note: The BASIC file number is not the
same thing as the DOS file handle number.
example:
'Copy 4OOO bytes from video memory to a file
Open "Temp.SCN" for Output as #1 : Close#1 'this resets filesize to O if needed
Open "Temp.SCN" for Binary as #1
MemToFile 1,&HB8OO,O,4OOO : Close#1
FUNCTION: StartUpDir$
Returns the directory containing the currently running .EXE file. This is
handy for accessing data files associated with the current program. Note
that the directory ALWAYS ends with a backslash (\). This allows easy
concatenation of filenames to the directory name. If you need to perform a
CHDIR to the start up directory then you must remove the (\) from the directory
names other than the root directory.
example: SDir$=StartUpDir$
'SDir$ would have the general form C:\ (root directory) or C:\TEMP\MISC\
DataFile$=SDir$+"Temp.Dat"
If LEN(SDir$)=3 then CHDIR SDir$ else CHDIR LEFT$(SDir$,LEN(SDir$)-1)
FUNCTION: StartUpExec$
Returns the name of the currently running .EXE executable file. This can be
used to access data which has been added to the end of an .EXE file.
e.g. COPY/B TEMP.EXE+DATA.FIL PROGRAM.EXE
example: SExec$=StartUpExec$
Open SExec$ for Input as #2
Seek#2,EXEFileSize&+1 'EXE filesize (without added data) must be known
'....retrieve data here....
SUBROUTINE: VarToFile FileNum%,Variable,VariableSize%
Copies the specified number of bytes (VariableSize%) from memory at
the location of the Variable into the file (at the current file pointer
location) whose BASIC file number (FileNum%) is specified. The file must
already be opened in Binary mode. Note: The BASIC file number is not the
same thing as the DOS file handle number. This routine is handy for writing
from a TYPE variable directly into a file.
ex: TYPE NewVar:First as Integer:Second as Integer:END TYPE:Dim Temp as NewVar
Open "Temp.SCN" for Output as #1 : Close#1 'resets filesize to O if needed
Open "Temp.TMP" for Binary Access as #1
VarToFile 1,Temp.First,4 : Close#1 'writes both 2-byte integers
┌─────────────────────────────────────────────────────────────────────────────┐
│ JOYSTICK FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
FUNCTION: JoyStkAX%
Returns the X (horizontal) value of Joystick A.
example: JAX%=JoyStkAX%
FUNCTION: JoyStkAY%
Returns the Y (vertical) value of Joystick A.
example: JAY%=JoyStkAY%
FUNCTION: JoyStkAFire%
Returns -1 if the fire (top) button on Joystick A is pressed, otherwise it
returns O.
example: JAF%=JoyStkAFire%
FUNCTION: JoyStkABase%
Returns -1 if the base (bottom) button on Joystick A is pressed, otherwise it
returns O.
example: JAB%=JoyStkABase%
FUNCTION: JoyStkBX%
Returns the X (horizontal) value of Joystick B.
example: JBX%=JoyStkBX%
FUNCTION: JoyStkBY%
Returns the Y (vertical) value of Joystick B.
example: JBY%=JoyStkBY%
FUNCTION: JoyStkBFire%
Returns -1 if the fire (top) button on Joystick B is pressed, otherwise it
returns O.
example: JBF%=JoyStkBFire%
FUNCTION: JoyStkBBase%
Returns -1 if the base (bottom) button on Joystick B is pressed, otherwise it
returns O.
example: JBB%=JoyStkBBase%
┌─────────────────────────────────────────────────────────────────────────────┐
│ KEYBOARD FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
FUNCTION: CapsLock%
Returns -1 if the Caps-Lock state is ON, otherwise returns O.
example: X%=CapsLock%
SUBROUTINE: CapsLockOn
Turns ON the Caps-Lock state.
example: CapsLockOn
--or-- Call CapsLockOn
SUBROUTINE: CapsLockOff
Turns OFF the Caps-Lock state.
example: CapsLockOff
--or-- Call CapsLockOff
FUNCTION: GetKey%
Returns the keycode of the last key pressed (see the keycode table in the
appendix). Returns zero (O) if no key was pressed. This function does NOT
wait for a keypress. Note: GetKey% reads STDIN and thus can be redirected.
example: Do : K%=GetKey% : Loop While K%=O
FUNCTION: KeyAlt%
Returns -1 if either Alt key is pressed, otherwise returns O.
example: X%=KeyAlt%
FUNCTION: KeyLAlt%
Returns -1 if the Left Alt key is pressed, otherwise returns O.
example: X%=KeyLAlt%
FUNCTION: KeyRAlt%
Returns -1 if the Right Alt key is pressed, otherwise returns O.
example: X%=KeyRAlt%
FUNCTION: KeyCtrl%
Returns -1 if either Ctrl key is pressed, otherwise returns O.
example: X%=KeyCtrl%
FUNCTION: KeyLCtrl%
Returns -1 if the Left Ctrl key is pressed, otherwise returns O.
example: X%=KeyLCtrl%
FUNCTION: KeyRCtrl%
Returns -1 if the Right Ctrl key is pressed, otherwise returns O.
example: X%=KeyRCtrl%
FUNCTION: KeyPending%
Returns -1 if there is a keycode pending in the keyboard buffer, otherwise
returns O. This function does NOT retrieve the keycode. It simply signals
that a key has been pressed.
example: While Not KeyPending% : Wend 'loop until a key is pressed
K%=GetKey% 'get the keycode of that key
FUNCTION: KeyShift%
Returns -1 if either Shift key is pressed, otherwise returns O.
example: X%=KeyShift%
FUNCTION: KeyLShift%
Returns -1 if the Left Shift key is pressed, otherwise returns O.
example: X%=KeyLShift%
FUNCTION: KeyRShift%
Returns -1 if the Right Shift key is pressed, otherwise returns O.
example: X%=KeyRShift%
FUNCTION: NumLock%
Returns -1 if the Num-Lock state is ON, otherwise returns O.
example: X%=NumLock%
SUBROUTINE: NumLockOn
Turns ON the Num-Lock state.
example: NumLockOn
--or-- Call NumLockOn
SUBROUTINE: NumLockOff
Turns OFF the Num-Lock state.
example: NumLockOff
--or-- Call NumLockOff
SUBROUTINE: PressAnyKey
Pauses until a key is pressed. No prompt is displayed and no value is returned.
example: PressAnyKey
--or-- Call PressAnyKey
FUNCTION: ScrollLock%
Returns -1 if the Scroll-Lock state is ON, otherwise returns O.
example: X%=ScrollLock%
SUBROUTINE: ScrollLockOn
Turns ON the Scroll-Lock state.
example: ScrollLockOn
--or-- Call ScrollLockOn
SUBROUTINE: ScrollLockOff
Turns OFF the Scroll-Lock state.
example: ScrollLockOff
--or-- Call ScrollLockOff
SUBROUTINE: SetTypematic Rate%, Delay%
Sets the keyboard typematic rate and delay on PC-AT class machines only. Will
not work on PC-XT machines. Note: cps is characters-per-second.
┌─────┬────╥─────┬────╥─────┬────╥─────┬────┐ ┌──────┬────┐
│Rate%│ cps║Rate%│ cps║Rate%│ cps║Rate%│ cps│ │Delay%│msec│
├─────┼────╫─────┼────╫─────┼────╫─────┼────┤ ├──────┼────┤
│ O │3O.O║ 8 │15.O║ 16 │ 7.5║ 24 │ 3.7│ │ O │ 25O│
│ 1 │26.7║ 9 │13.3║ 17 │ 6.7║ 25 │ 3.3│ │ 1 │ 5OO│
│ 2 │24.O║ 1O │12.O║ 18 │ 6.O║ 26 │ 3.O│ │ 2 │ 75O│
│ 3 │21.8║ 11 │1O.9║ 19 │ 5.5║ 27 │ 2.7│ │ 3 │1OOO│
│ 4 │2O.O║ 12 │1O.O║ 2O │ 5.O║ 28 │ 2.5│ └──────┴────┘
│ 5 │18.5║ 13 │ 9.2║ 21 │ 4.6║ 29 │ 2.3│
│ 6 │17.1║ 14 │ 8.6║ 22 │ 4.3║ 3O │ 2.1│
│ 7 │16.O║ 15 │ 8.O║ 23 │ 4.O║ 31 │ 2.O│
└─────┴────╨─────┴────╨─────┴────╨─────┴────┘
example: SetTypematic 8,1 'set 15 cps rate and 5OO msec delay
SUBROUTINE: TypeAhead Text$
Places the Text$ string into the keyboard buffer as if the user had typed
it from the keyboard. If an extended key sequence is desired (such as F3),
place a CHR$(O) into the string followed by the CHR$(scan-code) of that key.
Scan codes are listed in the appendix. Note that the maximum number of
keystrokes which can be placed into the keyboard buffer is 15.
example: TypeAhead "DIR"+CHR$(13) 'DIR command followed by the Enter key
FUNCTION: WaitKey%
Returns the keycode of the last key pressed (see the keycode table in the
appendix). This function WAITS for a keypress. Note: WaitKey% reads STDIN
and thus can be redirected.
example: K%=WaitKey%
SUBROUTINE: WaitSpecKey SpecKey%
Pauses the program until the user presses the specified key. (see the keycode
table in the appendix). Note: WaitSpecKey reads STDIN and thus can be
redirected.
example: WaitSpecKey 27 'would wait for the Escape key to be pressed
┌─────────────────────────────────────────────────────────────────────────────┐
│ MEMORY FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
FUNCTION: BitGet% (ArraySeg%, Element%)
SUBROUTINE: BitSet ArraySeg%, Element%, Value%
These routines will allow the programmer to make use of a BIT array. The
BitGet% function returns a value of O or -1 based upon the setting of a single
bit in the memory block which starts at paragraph (ArraySeg%) and offset zero.
Note that the memory block must start on an even paragraph boundary. The
SETMEM and GetMem routines can be used to allocate sufficient memory space for
the bit array. The Element% operand (O to Max Element) specifies which bit is
to be accessed. BitSet sets the bit array element to Value% (O or 1 (-1 can
also be used)). For example, suppose a 4O35 element bit array is to be used.
Note that the elements (i.e. array subscripts) would range from O to 4O34.
A%=SETMEM(-537) '4O35 bits / 8 bits-per-byte = 5O4.375 bytes so use 5O5 bytes
'(always round UP)
'tell Quick-BASIC's far heap manager to release 5O5 bytes
'(plus extra 32 bytes allows for rounding in the next step)
ASeg%=GetMem%(32) 'specify the number of PARAGRAPHS (1 paragraph=16 bytes)
'5O5 bytes / 16 bytes-per-paragraph = 31.5625 paragraphs
'round UP to 32 paragraphs
'because DOS allocates memory in 16-byte blocks
BitSet ASeg%,999,O 'sets element 999 to zero
B%=BitGet%(ASeg%,999) 'B% would be zero
BitSet ASeg%,999,1 'sets element 999 to one (note:BitSet ASeg%,999,-1 ok too)
B%=BitGet%(ASeg%,999) 'B% would be -1
FUNCTION: DefSeg%
Returns the segment used in the last DEF SEG statement. If DEF SEG has not
yet been called, this function returns BASIC's default data segment which is
called DGROUP. For example:
DEF SEG = O 'set a new segment (for use with PEEK/POKE statements)
NewSeg%=DefSeg% 'the variable NewSeg% now contains zero
SUBROUTINE: Encrypt MemSegment%,MemPointer%,NumberOfBytes%,XORByteValue%
This routine performs a simple encryption procedure on the specified memory
area. To unencrypt, just use the Encrypt routine a second time. It is a bit
more thorough than the MemXORByte routine. Special note: The memory blocks
must be the same size and the XORByteValue% must be the same when encrypting
and unencrypting.
-example for encrypting a block of memory, copying it, then unencrypting it:
Encrypt MemSeg1%,MemOfs1%,NumBytes%,123
'memory block is encrypted before it is copied
MemCopy MemSeg1%,MemSeg1%,MemSeg2%,MemOfs2%,NumBytes%)
'memory block, which has been encrypted, is copied to the destination location
Encrypt MemSeg2%,MemOfs2%,NumBytes%,123
'memory block is unencrypted at the destination location (after being copied)
-example for encrypting/unencrypting a string:
Encrypt VARSEG(Text$),SADD(Text$),LEN(Text$),255 'string is now encrypted
Encrypt VARSEG(Text$),SADD(Text$),LEN(Text$),255 'string is now unencrypted
FUNCTION: EnvironSeg%
Returns the memory segment containing the environment belonging to the currently
running .EXE program.
example: ESeg% = EnvironSeg%
DEF SEG = ESeg% 'you can now use PEEK to look for COMSPEC etc.
FUNCTION: GetMem% (NumPara%)
FUNCTION: RelMem% (SegAdr%)
The GetMem% function is used to allocate a block of memory which has a size
(in 16-byte paragraphs) of NumPara%. Note that DOS allocates memory in 16-byte
blocks called paragraphs. The RelMem% function releases (to DOS) the memory
arena located at paragraph SegAdr%. GetMem% returns zero (O) if DOS cannot
find enough memory to satisfy the request, otherwise GetMem% returns the
paragraph (segment) at which the allocated memory block starts. Note that
allocated memory blocks always start on a paragraph boundary (i.e. para:OOOO
(offset of zero)). Your program MUST use SETMEM to tell Quick-BASIC's far heap
manager that it must relinquish control of a block of memory. For example:
A%=SETMEM(-(16384&+32&)) 'ask BASIC to release 16k of memory so DOS can have it
'(+32 bytes as a precaution for rounding)
Segm%=GetMem%(1O24) 'ask DOS for 16k of memory
'(1O24 paragraphs x 16 bytes-per-paragraph = 16384 bytes)
'..use the 16k-byte block of memory starting at Segm%:OOOO for any purpose...
ErCode%=RelMem%(Segm%) 'release the block of memory back to DOS
A%=SETMEM(16384&+32&) 'tell BASIC to reclaim 16k block from DOS
'note: all allocated memory is automatically returned to DOS when your
'program ends - so that the last two lines of program code are optional
FUNCTION: LowMem% (MemAdr%)
Returns the value of the BYTE located in low memory (paragraph (segment) zero
and offset MemAdr%). "The Programmer's PC Sourcebook" from MicroSoft Press has
a table showing the information that is stored in low memory.
For example,
A%=LowMem%(&H46C) 'get the byte at location OOOO:O46C (hexadecimal address)
FUNCTION: MemChkSum& (MemSeg%, MemPtr%, NumBytes%)
Returns a long integer value representing the sum of all the bytes in the
memory block (located at MemSeg%:MemPtr% and having a length of NumBytes%).
example: A&=MemChkSum&(&hB8OO,O,4OOO) 'get check sum of color text screen memory
FUNCTION: MemCompare% (Seg1%,Adr1%,Seg2%,Adr2%,Bytes%)
Compares the contents of two memory blocks to determine if they contain
exactly the same data. The function returns -1 if the blocks are the same,
otherwise it returns zero. The first memory block is located at address
Seg1%:Adr1% (segment:offset), while the second memory block is located at
address Seg2%:Adr2% (segment:offset). The Bytes% operand is used to specify
the number of bytes, from each block, that are to be compared. Note: Refer to
the section on segmented memory at the beginning of this documentation.
example: A%=MemCompare%(&H1234,&H5678,&H9876,&H5432,128) 'addresses are in hex
'compare 128 bytes of the memory blocks starting at 1234:5678 and 9876:5432
'A=-1 if the two memory blocks are the same, otherwise A%=O
SUBROUTINE: MemCopy Seg1%,Adr1%,Seg2%,Adr2%,Bytes%
Copies the memory block starting at Seg1%:Adr1% to the memory block starting at
Seg2%:Adr2%. The Bytes% operand specifies the number of bytes to copy.
example:
MemCopy &hB8OO,O,&h7654,&h321O,4OOO
'copies 4OOO bytes from memory block B8OO:OOOO to memory block 7654:321O (hex)
SUBROUTINE: MemFillByte MemSeg%,MemPtr%,NumBytes%,FillValue%
Fills the memory block, that starts at MemSeg%:MemPtr% and has a length of
NumBytes%, with the specified FillValue% byte.
example: MemFillByte &hB8OO,O,4OOO,32 'fill color screen with black/green spaces
SUBROUTINE: MemFillWord MemSeg%,MemPtr%,NumWords%,FillValue%
Fills the memory block, that starts at MemSeg%:MemPtr% and has a length of
(NumWords% * 2) bytes, with the specified FillValue% word.
example: MemFill &hB8OO,O,2OOO,8224 'fill color screen with black/green spaces
SUBROUTINE: MemSwap Seg1%,Adr1%,Seg2%,Adr2%,Bytes%
Swaps the contents of two memory blocks. The first memory block is located at
address Seg1%:Adr1% (segment:offset), while the second memory block is located
at address Seg2%:Adr2% (segment:offset). The Bytes% operand is used to specify
the number of bytes, from each block, that are to be swapped.
SUBROUTINE: MemXORByte MemSeg%,MemPtr%,NumBytes%,XORByteVal%
Exclusive-ORs each byte in the memory block, located at address MemSeg%:MemPtr%
and having a length of NumBytes%, with the XORByteVal%. This routine could be
used to make a simple encrypt/decrypt function for a block of memory.
example: MemXORByte &hB8OO,O,4OOO,255
SUBROUTINE: MemXORWord MemSeg%,MemPtr%,NumWords%,XORWordVal%
Exclusive-ORs each word in the memory block, located at address MemSeg%:MemPtr%
and having a length in bytes of (NumWords% * 2), with the XORWordVal%. This
routine can be used to make an encrypt/decrypt function for a block of memory.
example: MemXORWord &hB8OO,O,2OOO,&hFFOO 'each word is 2 bytes in length
SUBROUTINE: MinimizePtr OldSeg%,OldPtr%,NewSeg%,NewPtr%
Reduces the size of the pointer (offset) of the given segmented address. The
original address is given as OldSeg%:OldPtr% while the resultant (minimized
pointer) address is given as NewSeg%:NewPtr%. This function forces the NewPtr%
variable to have a value in the range of O to 15. It is useful to minimize an
address prior to using MemCopy, MemCompare etc. because an SI or DI register
overflow can occur if the offset (pointer) plus the number of bytes to
move/compare etc. exceeds 65535 (FFFF hex).
FUNCTION: PeekByte% (MemSeg%, MemAdr%)
Returns the value of a single byte in memory at address MemSeg%:MemAdr%.
Unlike BASIC's PEEK command, this function allows the user to specify the
memory segment to use. This means that the DEF SEG command does not have to
be used prior to peeking at the memory location. For example,
A%=PeekByte%(&hB8OO,&h1234) 'A% is set equal to the byte at B8OO:1234 (hex)
FUNCTION: PeekWord% (MemSeg%, MemAdr%)
Returns the value of a 2-byte word in memory starting at address
MemSeg%:MemAdr%. Note that two successive bytes are read by this function
in order to build a 2-byte word return value. For example:
A%=PeekWord%(&h1234,&h5678) 'is equivalent to:
'DEF SEG = &h1234
'A% = PEEK(&h5678) + ( 256% * PEEK(&h5679) )
FUNCTION: PeekLong& (MemSeg%, MemAdr%)
Returns the value of a 4-byte double word, in memory starting at address
MemSeg%:MemAdr%, into a long (&) integer.
Note that four successive bytes are read by this function in order to build a
4-byte long integer return value. For example:
A&=PeekLong&(O,&h46C) 'reads the PC's timer tick value (4 bytes long)
SUBROUTINE: PokeByte MemSeg%, MemAdr%, Value%
Places the byte Value% into memory at MemSeg%:MemAdr%. Note that it does not
require the DEF SEG command that BASIC's POKE statement uses. For example,
PokeByte &hB8OO,&hO5OO,32 'puts a space in the color text screen memory area
SUBROUTINE: PokeWord MemSeg%, MemAdr%, Value%
Places the 2-byte integer Value% into two consecutive (byte-wide) memory
locations starting at MemSeg%:MemAdr%. For example,
PokeWord &hB8OO,&hO5OO,83O4
'places 83O4 into memory at B8OO:O5OO (low byte at :O5OO and high byte at :O5O1)
SUBROUTINE: PokeLong MemSeg%, MemAdr%, Value&
Places the 4-byte integer Value& into four consecutive (byte-wide) memory
locations starting at MemSeg%:MemAdr%. For example,
PokeLong &h9876,&h5432,&h12345678 'lowest order byte at lowest address (offset)
'places &h78 at 9876:5432 (hex address)
'places &h56 at 9876:5433
'places &h34 at 9876:5434
'places &h12 at 9876:5435
FUNCTION: PSPSeg%
Returns the PSP segment of the current process. The PSP contains pointers
to the parent process PSP segment (offset 16h) and to the environment segment
(offset 2Ch). It also contains the command line parameters (starting at offset
81h with the command line parameter length at offset 8Oh).
For example, get the command line (including the leading space)
PSeg%=PSPSeg% : DEF SEG=PSeg% : Cmd$=""
For I%=1 to PEEK(&h8O):Cmd$=Cmd$+CHR$(PEEK(&h8O+I%)):Next I%
FUNCTION: ReadCMOS% (CMOSAdr%)
Returns the value from the specified address (O to 53) in CMOS memory (PC-AT+
using MC146818A real time clock chip only). Some important addresses are:
O=seconds 2=minutes 4=hours 6=day-of-week 7=day 8=month 9=year. Note
that many of these values are stored in BCD (binary-coded-decimal) form.
Suppose the current minute is 59 (normal decimal form). It is stored in CMOS
RAM as 59 BCD. Note that BCD is like hexadecimal without the A through F
digits. This means that 59 BCD is actually stored as 59 hex.
example:
BCDmin% = ReadCMOS%(2)
Minutes% = (1O% * ( BCDmin% \ 16% )) + (BCDmin% AND 15%) 'convert BCD to decimal
'--or you can use the BCDtoDEC% function--
Minutes% = BCDtoDEC%(BCDmin%) 'convert BCD to DECimal
FUNCTION: RelMem% (SegAdr%)
** see GetMem function **
SUBROUTINE: VarSegPtr Variable, SegAdr%, PtrAdr%
Calculates the 'minimized' segment:offset address of the given Variable (any
kind) and returns the segment (paragraph) in SegAdr% and returns the offset
(pointer) in PtrAdr%. For example,
VarSegPtr Test%,MemSeg%,MemPtr%
'---is the same as---
MSeg%=VARSEG(Test%)
MAdr%=VARPTR(Test%)
MinimizePtr MSeg%,MAdr%,MemSeg%,MemPtr%
SUBROUTINE: WriteCMOS CMOSAdr%, Value%
Writes the byte Value% to CMOS RAM address CMOSAdr%. Note that the address
must be in the range of O to 9 only. See the ReadCMOS% function for more
details. For example:
WriteCMOS 2,&h59 'write 59 (in BCD form) to CMOS address 2 (minutes)
'---or you can use the DECtoBCD% function---
A%=DECtoBCD%(59%)
WriteCMOS 2,A% 'write 59 (in BCD form) to CMOS address 2 (minutes)
┌─────────────────────────────────────────────────────────────────────────────┐
│ MOUSE FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
Note: The MsReset% function MUST be called BEFORE ANY other mouse functions
or subroutines can be accessed !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
FUNCTION: MsBtn%
Returns zero if no mouse buttons are being pressed, otherwise it returns a
composite value using the binary weighting of each mouse button.
Left Button = 1
Right Button = 2
Center Button = 4
example: A%=MsBtn% 'A% would be 7 (1+2+4) if all mouse buttons are being pressed
FUNCTION: MsCBtn%
Returns -1 if the center mouse button is being pressed and zero otherwise.
Note that some earlier versions of the mouse driver do not report the status
of the center mouse button.
example: A%=MsCBtn%
FUNCTION: MsClickCount% (WhichButton%)
Returns the number of times the specified button has been pressed since the
last call to this routine. This is useful in checking for a double-click on a
menu option etc. Note that the click-count for the specified button is reset
to zero after this routine is called. The WhichButton% operand should be
O for the left mouse button, 1 for the right button and 2 for the center button.
example: A%=MsClickCount%(1)
'A% will be the number of times that the right mouse button has been
'pressed since the last call to this routine
SUBROUTINE: MsGetCsrPos CsrType%, Row%, Column%
SUBROUTINE: MsSetCsrPos CsrType%, Row%, Column%
MsGetCsrPos returns the position of the mouse pointer in the Row%, Column%
variables. In graphics mode, the mouse pointer "hot-spot" position is returned.
MsSetCsrPos sets the mouse pointer position to the values specified by the
Row% and Column% variables.
If CsrType% is O (text mode):
Row% will be 1 to 25 (text-mode row)
Column% will be 1 to 8O (text-mode column)
If CsrType% is 1 (graphics mode):
Row% will be the vertical position (O to maximum row [in pixels])
Column% will be the horizontal position (O to maximum column [in pixels])
Note: Row%=O and Column%=O is the upper-left corner of the graphics mode screen
example: MsGetCsrPos O,MRow%,MCol%
--or--
Call MsGetCsrPos(O,MRow%,MCol%)
'returns MRow% (row) and MCol% (column) of the text-mode mouse cursor
'Note: see the InBox% function to determine if the mouse is in a certain
' area ("box") on the screen
example: MsSetCsrPos O,13,4O 'set text-mode mouse cursor to row=13 and column=4O
--or--
Call MsSetCsrPos(O,13,4O)
SUBROUTINE: MsGetSensPct XMicks%, YMicks%, DblSpdMicks%
SUBROUTINE: MsSetSensPct XMicks%, YMicks%, DblSpdMicks%
The MsGetSensPct routine returns a percentage (1 to 1OO) of the maximum
mouse sensitivity in the operand variables. The MsSetSensPct routine sets the
percentage of maximum mouse sensitivity (1 to 1OO) for the operand variables.
XMicks% is (1 to 1OO) percent of the maximum horizontal mouse sensitivity which
is in mickeys-per-pixel. Standard mouse=2OO mickeys-per-inch of travel.
YMicks% is (1 to 1OO) percent of the maximum vertical mouse sensitivity which is
in mickeys-per-pixel.
DblSpdMicks% is (1 to 1OO) percent of the default double speed threshold. The
double speed threshold is the mouse travel speed (which is measured in
mickeys-per-second) at which the mouse sensitivity is doubled.
SUBROUTINE: MsGrPtrShape HotSptLeft%,HotSptTop%,SegPtrBfr%,OfsPtrBfr%
Defines the shape of the mouse graphics cursor. In normal graphics modes the
graphics cursor has a size of 16-by-16 pixels. The "hot-spot", which is the
point inside the 16-by-16 block that is reported to the mouse driver as the
cursor position, is located HotSptLeft% pixels from the left side and HotSptTop%
pixels from the top of the 16-by-16 graphics cursor block. The shape of the
graphics cursor is defined by a block of data which has a segment:offset
address of SegPtrBfr%:OfsPtrBfr%. The 64-byte data block consists of a screen
AND-mask (1 word-by-16) followed by a cursor XOR-mask (1 word-by-16). A "word"
is 2 bytes or 16 bits in length so that a 16bit-by-16bit AND mask followed by
a 16bit-by-16bit XOR mask can be stored in 64 bytes of memory. For example,
DIM Csr%(31) 'O to 15 for AND-mask 16 to 31 for XOR-mask
Csr%(OO)=&hE1FF '111OOOO111111111 ┐
Csr%(O1)=&hE1FF '111OOOO111111111 │
Csr%(O2)=&hE1FF '111OOOO111111111 │
Csr%(O3)=&hE1FF '111OOOO111111111 │
Csr%(O4)=&hE1FF '111OOOO111111111 │
Csr%(O5)=&hEOOO '111OOOOOOOOOOOOO │
Csr%(O6)=&hEOOO '111OOOOOOOOOOOOO │
Csr%(O7)=&hEOOO '111OOOOOOOOOOOOO ├──── AND-Mask ─┐
Csr%(O8)=O 'OOOOOOOOOOOOOOOO │ (Screen) │
Csr%(O9)=O 'OOOOOOOOOOOOOOOO │ │
Csr%(1O)=O 'OOOOOOOOOOOOOOOO │ │
Csr%(11)=O 'OOOOOOOOOOOOOOOO │ │
Csr%(12)=O 'OOOOOOOOOOOOOOOO │ │
Csr%(13)=O 'OOOOOOOOOOOOOOOO │ │
Csr%(14)=O 'OOOOOOOOOOOOOOOO │ │
Csr%(15)=O 'OOOOOOOOOOOOOOOO ┘ ├─ Notice the shape of a
Csr%(16)=&h1EOO 'OOO1111OOOOOOOOO ┐ │ hand in both masks
Csr%(17)=&h12OO 'OOO1OO1OOOOOOOOO │ │
Csr%(18)=&h12OO 'OOO1OO1OOOOOOOOO │ │
Csr%(19)=&h12OO 'OOO1OO1OOOOOOOOO │ │
Csr%(2O)=&h12OO 'OOO1OO1OOOOOOOOO │ │
Csr%(21)=&h13FF 'OOO1OO1111111111 │ │
Csr%(22)=&h1249 'OOO1OO1OO1OO1OO1 │ │
Csr%(23)=&h1249 'OOO1OO1OO1OO1OO1 ├──── XOR-Mask ─┘
Csr%(24)=&hF249 '1111OO1OO1OO1OO1 │ (Cursor)
Csr%(25)=&h9OO1 '1OO1OOOOOOOOOOO1 │
Csr%(26)=&h9OO1 '1OO1OOOOOOOOOOO1 │
Csr%(27)=&h9OO1 '1OO1OOOOOOOOOOO1 │
Csr%(28)=&h8OO1 '1OOOOOOOOOOOOOO1 │
Csr%(29)=&h8OO1 '1OOOOOOOOOOOOOO1 │
Csr%(3O)=&h8OO1 '1OOOOOOOOOOOOOO1 │
Csr%(31)=&hFFFF '1111111111111111 ┘
MsGrPtrShape 5,O,VARSEG(Csr%(O)),VARPTR(Csr%(O)) : MsShow 'needed to show it
SUBROUTINE: MsHide
Turns the mouse cursor OFF so that it is not visible on the screen. Note that
writing over the area containing the mouse cursor will remove it from the
screen. It is usually best to hide the mouse cursor prior to writing/printing
to the screen. It can be restored (using MsShow) later in the program.
example: MsHide
--or--
Call MsHide
FUNCTION: MsLBtn%
Returns -1 if the left mouse button is being pressed and zero otherwise.
example: While Not MsLBtn%
Wend 'exit loop when left mouse button is pressed
FUNCTION: MsRBtn%
Returns -1 if the right mouse button is being pressed and zero otherwise.
example: A%=MsRBtn%
FUNCTION: MsReset%
Resets the mouse driver and returns the status of the mouse. This function
returns -1 if a mouse is present and zero if no mouse was found. This
function MUST be called prior to calling any other mouse routines. Normally
the mouse should be reset at the beginning (and end) of the program. Note that
calling the MsReset% function also hides the mouse cursor. If your program
changes the screen mode, MsReset% should be called after the change is made.
SUBROUTINE: MsSetCsrPos CsrType%, Row%, Column%
** see MsGetCsrPos subroutine **
SUBROUTINE: MsSetLimit CsrType%,MinRow%,MinColumn%,MaxRow%,MaxColumn%
Restricts mouse movement on the screen to a box defined by the upper-left
corner (MinRow%,MinColumn%) and the lower-right corner (MaxRow%,MaxColumn%).
If CsrType% is O (text mode):
Rows are 1 to 25 and columns are 1 to 8O for the text-mode screen.
If CsrType% is 1 (graphics mode):
Rows are O to maximum row value (in pixels) and columns are O to maximum
column value (in pixels).
Note: row=O and column=O specifies the upper-left corner of the graphics screen
SUBROUTINE: MsSetSens XMicks%, YMicks%, DblSpdMicks%
Sets the mouse sensitivity according the operand values:
XMicks% is horizontal mouse sensitivity in mickeys-per-pixel. There are about
2OO mickeys-per-inch of mouse movement for a normal (default) mouse.
YMicks% is vertical mouse sensitivity in mickeys-per-pixel.
DblSpdMicks% is the double speed threshold and is the mouse speed (measured in
mickeys-per-second) at which the mouse sensitivity (mickeys-per-pixel) is
doubled. If the screen size (rows and columns in pixels) is known, it is
possible to set the sensitivity so that a predetermined amount of mouse travel
will result in a known amount of screen mouse cursor movement.
SUBROUTINE: MsSetSensPct XMicks%,YMicks%,DblSpdMicks%
** see MsGetSensPct subroutine **
SUBROUTINE: MsShow
Turns the mouse cursor ON so that it becomes visible on the screen.
example: MsShow
--or--
Call MsShow
SUBROUTINE: MsTxtPtrType SHPtr%, ANDMask%, XORMask%
Defines the text-mode mouse pointer type. SHPtr% determines whether to use a
software or hardware cursor. Note that the default text-mode pointer works
fairly well. You might have to experiment with the AND/XOR mask values if
you wish to use this routine.
If SHPtr% = O (Software Cursor) then:
ANDMask% is logically ANDed with the ASCII character and color attribute
at the mouse cursor position. (see bit table below)
XORMask% is logically XORed with the ASCII character and color attribute
at the mouse cursor position. (see bit table below)
Bit O to 7 : ASCII character code
Bit 8 to 1O : Foreground color────────┐ see programming section
Bit 11 : Intensity (bright if 1) ├─at beginning of document
Bit 12 to 14 : Background color │ for color codes
Bit 15 : Blink Bit (blink if 1)──┘
If SHPtr% = 1 (Hardware Cursor) then:
ANDMask% is the starting scan line of the block cursor
XORMask% is the ending scan line of the block cursor.
example: MsTxtPtrType O,&h7FFF,&h77OO
FUNCTION: MsWaitClick% (ClickMask%)
Waits until a specified mouse button is pressed. The ClickMask% is logically
ANDed with the button press information (see: MsBtn% function) and returns
with this modified information when:
[ (button press info) AND (ClickMask%) ] <> zero.
example: A%=MsWaitClick%(3)
'wait for either left or right mouse button
'left=1 right=2 ---> 1+2 = 3 = ClickMask%
'A%=1 if left button pressed
'A%=2 if right button pressed
'A%=3 if both buttons pressed
┌─────────────────────────────────────────────────────────────────────────────┐
│ NUMERIC FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
FUNCTION: BCDtoDEC% (BCDVal%)
FUNCTION: DECtoBCD% (DECVal%)
These functions convert numbers between BCD and DECimal forms. Note that the
values must be in the range (OO to 99 BCD) and (O to 99 DECimal). Numbers
outside this range will yield unpredictable return values. These functions
are very handy when using the ReadCMOS and WriteCMOS functions.
example: A% = BCDtoDEC%(&h99) 'A% would be 99 decimal
A% = DECtoBCD%(99%) 'A% would be &h99 (or 99 BCD)
FUNCTION: Caps% (AsciiValue%)
If the AsciiValue% is between 97 and 122 (inclusive), which corresponds to
ASCII 97="a" and ASCII 122="z", then the return value is (AsciiValue%-32).
This converts lower-case ASCII integer values into upper-case values.
example: X% = Caps%(45) ' X%=45 (no change - ASCII 45 is not alphabetic)
X% = Caps%(98) ' X%=66 (ASCII 98 = "b" and ASCII 66 = "B")
X% = Caps%(GetKey%) 'forces GetKey% to return all upper-case (caps)
X% = Caps%(WaitKey%) 'forces WaitKey% to return all upper-case (caps)
FUNCTION: ChgBit% (Value%, BitPos%, Operation%)
Changes the specified bit of Value% at position (BitPos%=O to 15) according to
the specified operation:
Operation% = O sets the specified bit to O
= 1 sets the specified bit to 1
= -1 complements the specified bit (logical NOT).
example: A%=ChgBit%(Test%,12,1)
'sets A% equal to Test% except that bit 12 (binary value 4O96) is set to 1.
'note: Bit 15 is the most-significant-bit and Bit O is the least-significant-bit
FUNCTION: HighWord% (LongInt&)
Returns the high order 2-byte word of the specified long (4-byte) integer value.
example: A%=HighWord%(&h12345678) 'A% would be &h1234
'note: same as A%=&h12345678\65536& but
' does not use division function
FUNCTION: InBox% (TestRow%, TestCol%, Row1%, Col1%, Row2%, Col2%)
Returns -1 if TestRow% is between Row1% and Row2% (inclusive) and if TestCol% is
between Col1% and Col2% (inclusive). It returns zero otherwise. This function
was designed primarily to determine if a given row and column (e.g. mouse
cursor coordinates) are within a given "box" on the screen, where Row1%,Col1%
is the upper-left corner and Row2%,Col2% is the lower-right corner of the "box".
This is not the only use for this function. Note that this function uses SIGNED
integer values (-32768 to 32767) unlike many of the other functions.
example: If InBox%(Row%,Col%,1,1,25,8O) then print "ON SCREEN"
FUNCTION: InRange% (TestVal%, LowVal%, HighVal%)
Returns -1 if TestVal% is between LowVal% and HighVal% (inclusive). It returns
zero otherwise. Note that this function uses SIGNED integer values (-32768 to
32767) unlike many of the other functions.
example: If InRange%(Test%,1,1OO) then print "IN RANGE"
'----is the same as----
If (Test% >= 1) AND (Test% <=1OO) then print "IN RANGE"
FUNCTION: Larger% ( Value1% , Value2% )
Returns the larger of the two SIGNED integers. (-32768 to 32767)
example: A%=Larger%(-1OO,1OO) 'A% would be 1OO
FUNCTION: LargerL& ( Value1& , Value2& )
Returns the larger of the two SIGNED long (4-byte) integers.
example: A&=LargerL&(-1OOOOO,1OOOOO) 'A& would be 1OOOOO
FUNCTION: LowWord% (LongInt&)
Returns the low order 2-byte word of the specified long (4-byte) integer value.
example: A%=LowWord%(&h12345678) 'A% would be &h5678
'note: same as A%=(&h12345678 AND 65535&)
FUNCTION: NoCaps% (AsciiValue%)
If the AsciiValue% is between 65 and 9O (inclusive), which corresponds to
ASCII 65="A" and ASCII 9O="Z", then the return value is (AsciiValue%+32).
This converts upper-case ASCII integer values into lower-case values.
example: X% = NoCaps%(45) ' X%=45 (no change - ASCII 45 is not alphabetic)
X% = NoCaps%(66) ' X%=98 ( ASCII 66 = "B" and ASCII 98 = "b" )
X% = NoCaps%(GetKey%) 'forces GetKey% to return lower-case (no caps)
X% = NoCaps%(WaitKey%) 'forces WaitKey% to return lower-case (no caps)
FUNCTION: PowerOf2% (Power%)
Returns a value equal to: 2 raised to a Power% (O to 15).
example: A%=PowerOf2%(1O) 'A% would be 2^1O = 1O24.
FUNCTION: RandNum% (MaxNum%)
Returns a random integer between zero and MaxNum%. This function automatically
seeds the random number generator with the timer tick value when it is called
for the first time in a program.
example: A%=RandNum%(5O) 'A% will be between O and 5O (inclusive).
SUBROUTINE: SetInBox Row%, Column%, Row1%, Column1%, Row2%, Column2%
If the Row%,Column% values are outside of the "box" (formed by Row1%,Column1%
as the upper-left corner and Row2%,Column2% as the lower-right corner) then
the values of Row% and/or Column% are automatically adjusted so that they are
within the confines of the "box". Note that this function uses SIGNED integer
values (-32768 to 32767) unlike many of the other functions. For example:
SetInBox Row%,Col%,1,1,25,8O 'make sure that Row%,Col% are on the screen
SUBROUTINE: SetInRange TestVal%, LowVal%, HighVal%
If TestVal% is less than LowVal% then TestVal% is set equal to LowVal%. If
TestVal% is greater than HighVal% then TestVal% is set equal to HighVal%.
Note that this function uses SIGNED integer values (-32768 to 32767) unlike
many of the other functions.
example: SetInRange Test%,1,1OO 'make sure Test% is inside the range of 1 to 1OO
'----is the same as----
If (Test% < 1) Then Test%=1
If (Test% > 1OO) Then Test%=1OO
FUNCTION: ShiftLeft% (Value%, NumBits%)
Returns the Value% shifted (bitwise) to the left by the specified number of
bits (NumBits%). Each bit position that the number is shifted is equivalent
to multiplying by 2. Bits shifted past bit 15 are discarded.
example: A%=ShiftLeft%(12,3) 'A% would be 96 = (12 x (2^3))
Note: This function assumes Value% is UNsigned (O to 65535).
FUNCTION: ShiftRight% (Value%, NumBits%)
Returns the Value% shifted (bitwise) to the right by the specified number of
bits (NumBits%). Each bit position that the number is shifted is equivalent
to dividing by 2. Bits shifted past bit O are discarded.
example: A%=ShiftRight%(192,6) 'A% would be 3 = (192 \ (2^6))
Note: This function assumes Value% is UNsigned (O to 65535).
FUNCTION: Smaller% ( Value1% , Value2% )
Returns the smaller of the two SIGNED integers. (-32768 to 32767)
example: A%=Smaller%(-1OO,1OO) 'A% would be -1OO
FUNCTION: SmallerL& ( Value1& , Value2& )
Returns the smaller of the two SIGNED long (4-byte) integers.
example: A&=SmallerL&(-1OOOOO,1OOOOO) 'A& would be -1OOOOO
FUNCTION: SwapBytes% (Value%)
Swaps the upper and lower bytes of the 2-byte integer Value%.
example: A%=SwapBytes%(&h1234) 'A% would be &h3412
FUNCTION: TestBit% (Number%, BitPosition%)
Returns -1 if the specified bit (BitPosition%=O to 15) of the 2-byte integer
Number% is ON (bit equal to 1) and returns O if the bit is OFF (bit equal to O)
example: A%=TestBit%(Temp%,12)
'A% would be -1 if bit 12 (binary value 4O96) of Temp% is a 1
'A% would be O if bit 12 (binary value 4O96) of Temp% is a O
'note: Bit 15 is the most-significant-bit and Bit O is the least-significant-bit
FUNCTION: UnsComp% (Value1%,Value2%)
Performs an UNsigned comparison of the two 16-bit signed integer values.
signed unsigned unsigned
decimal decimal hexadecimal
──────── ──────── ───────────
┌──largest -1 = 65535 = &hFFFF
│ ∙ -32768 = 32768 = &h8OOO
│ ∙ 32767 = 32767 = &h7FFF
└──smallest O = O = &hOOOO
example: X% = UnsComp% (V1%,V2%) 'X% will be -1 if V1% < V2% ─┐
'X% will be O if V1% = V2% ├─UNsigned
'X% will be +1 if V1% > V2% ─┘ comparison
┌─────────────────────────────────────────────────────────────────────────────┐
│ SCREEN (ANSI) FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
The following functions/subroutines operate on the current ANSI device, which
can be changed by the ANSIHandle subroutine. The default ANSI device is
input=keyboard and output=screen, both of which are redirectable from the DOS
command line. ex: CTTY COM1
PROGNAME
--or-- ex: PROGNAME <COM1 >COM1
FUNCTION: ANSIBgColor%
Returns the last background color used in a call to the ANSIColor subroutine.
example: ANSIColor 3,4
BG%=ANSIBgColor% 'BG% would be 4
SUBROUTINE: ANSICls
Clears the screen on the ANSI output device in the current colors. The ANSI
cursor is also placed at the "home" position (upper-left corner of the screen
where row=1 and column=1).
example: ANSICls
--or-- Call ANSICls
SUBROUTINE: ANSIColor Foreground%, Background%
Changes the colors on the ANSI output device to the values specified. Note
that this function automatically maps Quick-BASIC's colors into ANSI colors.
example: ANSIColor 31,1
'sets ANSI colors to blinking-bright-white on blue background
SUBROUTINE: ANSIComInit ComPortNum%, BaudRate%, Parity%, WordSize%, StopBits%
Initializes the specified communications (serial) port for use with the other
ANSI commands. Valid values are:
ComPortNum% = 1 through 4 (for COM1 through COM4)
BaudRate% = 15O, 3OO, 6OO, 12OO, 24OO, 48OO, 96OO
Parity% = O(none) 1(odd) 2(even)
WordSize% = 7 or 8 bits
StopBits% = 1 or 2
Note: If you are planning to use the other ANSI commands after initializing a
com port, you must specify the ANSI handle as the negative equivalent of
the com port number (using the ANSIHandle command).
example: ANSIComInit 2,96OO,O,8,1
'init COM2 with 96OO baud, no parity, 8 bit data, 1 stop bit
ANSIHandle -2
'a negative handle number indicates a com port (in this case -2 = COM2)
FUNCTION: ANSIComStatus% (ComPortNum%)
Retrieves the status of the specified communications (serial) port. Each bit of
the returned value has a particular meaning as shown below:
Bit Hex Value Meaning
O = &hOOO1 CTS has changed
1 = &hOOO2 DSR has changed
2 = &hOOO4 Trailing Edge Ring Detector
3 = &hOOO8 Carrier Detect has changed
4 = &hOO1O CTS (Clear To Send)
5 = &hOO2O DSR (Data Set Ready)
6 = &hOO4O Ring Indicator
7 = &hOO8O Carrier Detect
8 = &hO1OO Received Data is now ready to be retrieved from the UART
9 = &hO2OO Overrun Error
1O = &hO4OO Parity Error
11 = &hO8OO Framing Error
12 = &h1OOO Break Detect
13 = &h2OOO Transmitter Holding Register is empty
14 = &h4OOO Transmitter Shift Register is empty
15 = &h8OOO Time Out (if this bit is 1, the other bits are unpredictable)
example: Stat% = ANSIComStatus% (3) 'get the status of COM3
Ring% = (Stat% AND &hOO4O) 'is the COM3 modem phone line ringing ?
If Ring% then Print "The phone is ringing !"
SUBROUTINE: ANSICsrRest
Restores the cursor to the position last saved by the ANSICsrSave subroutine.
example: ANSICsrRest
--or-- Call ANSICsrRest
SUBROUTINE: ANSICsrSave
Saves the coordinates of the current cursor position so that it can be restored
by the ANSICsrRest subroutine.
example: ANSICsrSave
--or-- Call ANSICsrSave
SUBROUTINE: ANSIDelLine
Deletes the current line (using default ANSI colors) starting at the current
cursor position and ending at the rightmost column.
example: ANSIDelLine
--or-- Call ANSIDelLine
SUBROUTINE: ANSIDown NumRows%
Moves the ANSI cursor down the specified number of rows. If the cursor
reaches the bottom line, no additional movement takes place.
example: ANSIDown 5 'moves the ANSI cursor down 5 rows
FUNCTION: ANSIFgColor%
Returns the last foreground color used in a call to the ANSIColor subroutine.
example: ANSIColor 3,4
FG%=ANSIFgColor% 'FG% would be 3
SUBROUTINE: ANSIHandle Handle%
Specifies the DOS file handle for the default ANSI device. The standard DOS
file handles are:
O = STDIN (keyboard)
1 = STDOUT (screen)
2 = STDERR (screen - used for error messages)
3 = STDAUX (COM1: serial port)
4 = STDPRN (LPT1: printer/parallel port)
If ANSIHandle is not called, the default is (input=keyboard, output=screen)
which can be redirected from the DOS command line (e.g. TEMP <COM1 >COM1 ).
Note: This routine changes the value of the ANSI input handle AND the ANSI
output handle.
Note: If the specified handle is negative (e.g. -1 to -4) then the ANSIKey% and
ANSIPrt routines use the BIOS Int 14h com port functions to access
COM1 (if -1) through COM4 (if -4). In MOST (but not all) cases, the
com port must be initialized using the ANSIComInit subroutine.
example: ANSIHandle 3 'set ANSI i/o to COM1: (use DOS)
example: ANSIHandle -2 'set ANSI i/o to COM2: (use BIOS)
SUBROUTINE: ANSIHandleIn Handle%
Changes the ANSI input handle only, which is used by the ANSIKey% function.
example: ANSIHandleIn 5 'set ANSI input handle to 5 (an open DOS file)
SUBROUTINE: ANSIHandleOut Handle%
Changes the ANSI output handle only, which is used by the ANSIPrt subroutine.
example: ANSIHandleOut 5 'set ANSI output handle to 5 (an open DOS file)
SUBROUTINE: ANSIHome
Places the ANSI cursor at the "home" position (upper-left corner of the
screen where row=1 and column=1).
example: ANSIHome
--or-- Call ANSIHome
FUNCTION: ANSIKey%
Reads and returns the ASCII value of the next keystroke from the ANSI input
device. If no keystroke is pending, then the return value is -1.
This routine does not convert extended keycodes (as GetKey% and WaitKey% do), it
would simply return a null (zero) as the preamble code which would require your
program to retrieve the scan code as the next character. Standard ANSI keycodes
(up,down,right,left) would return ESCape (as ASCII 27) followed by the
left-bracket "[" (as ASCII 91), followed by the ANSI-sequence-end-code.
ANSI arrow-key codes: up=Esc[A down=Esc[B right=Esc[C left=Esc[D
example: AKey%=ANSIKey% 'AKey% contains next character from ANSI input device
Note: On three-wire RS-232 systems (Tx,Rx,GND), connect DSR to DTR and
connect RTS to CTS.
>>>Please bear in mind that the ANSIKey% function is not buffered, and therefore
if it is used to read communications (serial) port data, it MUST be called
often enough to prevent incoming data from overwriting the previous UART
receive data. This is referred to as "polling" the serial port. Serious
communications software would require "interrupt-driven" routines for
serial port I/O (especially input). The GPS library does NOT provide that.<<<
SUBROUTINE: ANSILeft NumColumns%
Moves the ANSI cursor the specified number of columns to the left. If the
cursor reaches the leftmost column, no additional movement takes place.
example: ANSILeft 15 'moves the ANSI cursor 15 columns to the left
SUBROUTINE: ANSILoc Row%, Column%
Places the ANSI cursor at the specified row and column. The upper-left corner
of the screen would be specified by Row%=1 and Column%=1. Note that some older
ANSI drivers do not allow the cursor to be placed on row 25.
example: ANSILoc 12,4O 'places the ANSI cursor at row=12 and column=4O
SUBROUTINE: ANSIPrt Text$
Prints the Text$ string to the ANSI output device. Note: This function does NOT
print a return/line-feed after printing the string. The ANSI cursor is left at
the position following the last character of Text$.
example: ANSIPrt "Now is the time for all good programmers to abandon C."
SUBROUTINE: ANSIPrtC Text$
This routine is identical to ANSIPrt, except that it DOES print a
return/line-feed after printing the string.
example: ANSIPrtC "The quick" : ANSIPrtC "brown fox"
This would cause printing to be done on two lines.
SUBROUTINE: ANSIPrtNum Number%
Prints the specified 2-byte integer Number% to the ANSI output device.
Note: This function does NOT add a leading space to positive numbers as BASIC
does. The ANSI cursor is left at the position following the last digit of
Number%.
example: ANSIPrt "(" : ANSIPrtNum 12345% : ANSIPrt ")" 'prints (12345)
SUBROUTINE: ANSIRight NumColumns%
Moves the ANSI cursor the specified number of columns to the right. If the
cursor reaches the rightmost column, no additional movement takes place.
example: ANSIRight 35 'moves the ANSI cursor 35 columns to the right
SUBROUTINE: ANSIUp NumRows%
Moves the ANSI cursor up the specified number of rows. If the cursor
reaches the top line, no additional movement takes place.
example: ANSIUp 4 'moves the ANSI cursor up 4 rows
┌─────────────────────────────────────────────────────────────────────────────┐
│ SCREEN FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
NOTE: ALL of the GPS library screen functions have been designed to work in
TEXT MODE ONLY !!! Be sure that you supply each screen function/subroutine
with row values between 1 and 25 and column values between 1 and 8O,
otherwise most will return without performing the specified function.
SUBROUTINE: AttrColor Attr%, Foreground%, Background%
Splits a color-attribute-byte value (Attr%) into separate variables (Foreground%
and Background%).
example: AttrColor 159,Fore%,Back% 'sets Fore%=31 (blinking bright white) and
'sets Back%=1 (blue background)
SUBROUTINE: Clrs Attr%
Clears the screen using the colors specified by the color-attribute-byte
(Attr%). See the beginning of this documentation for an explanation of this
byte. Note: Using the Clrs subroutine does NOT alter the default colors.
example: Clrs 7 'will clear the screen using foreground=7 background=O
FUNCTION: ColorAttr%(Foreground%, Background%)
Returns a color-attribute-byte value from the specified Foreground% and
Background% color values. This returned value can be used in several of the
GPS library screen functions.
example: FColor%=31 'blinking bright white foreground
BColor%=1 'blue background
A%=ColorAttr%(FColor%,BColor%) '(color-attribute-byte) A% would be 159
FUNCTION: ColorPDQ%
Returns the current color-attribute-byte value for a program LINKed with the PDQ
libraries from Crescent Software. There is a description of this byte at the
beginning of this documentation.
example: A%=ColorPDQ%
** Use only if LINKed with PDQ libraries
** Will not work inside QB editor/environment or with Quick-BASIC libraries
FUNCTION: ColorQB%
Returns the current color-attribute-byte value for a program LINKed with the
standard Quick-BASIC libraries (BCOM45.LIB and QB.LIB).
example: A%=ColorQB%
** Use only if LINKed with Quick-BASIC libraries
** Will not work inside QB editor/environment or with PDQ libraries
FUNCTION: MemToScreen% (see ScreenToMem% function)
SUBROUTINE: Prnt Text$, Row%, Column%, Attr%
Prints the Text$ on the screen at (Row%,Column%) using the colors specified by
the color-attribute-byte (Attr%). There is a description of this byte at the
beginning of this documentation. Note: the default colors are NOT altered.
example: Prnt "This is a test",12,35,31
'prints the text on (row=12,column=35) using white/blue colors
SUBROUTINE: PrntOver Text$, Row%, Column%
Prints the Text$ on the screen at (Row%,Column%) using the colors already on
the screen at the position where each character is to be printed.
example: COLOR 14,1 'sets color to yellow/blue
CLS 'clears the screen with yellow/blue
COLOR 12,3 'sets color to red/cyan (screen is still yellow/blue)
PrntOver "This is a test",12,35
'prints the text on (row=12,column=35) in yellow/blue
SUBROUTINE: ScreenAOX Row1%,Column1%,Row2%,Column2%,ANDmask%,ORmask%,XORmask%
Changes the ASCII-character and color-attribute within the screen "box"
(upper-left=Row1%,Column1% lower-right=Row2%,Column2%) with the 2-byte mask
values. The low-byte of each mask operates on the ASCII character while the
high-byte of each mask operates on the color-attribute-byte. The order of
operation is AND-OR-XOR. For example:
ScreenAOX 1,1,25,8O,&hFFFF,&h8OOO, O 'set blink bit ON
ScreenAOX 1,1,25,8O,&h7FFF, O, O 'set blink bit OFF
ScreenAOX 1,1,25,8O,&hFFFF,&hO8OO, O 'set bold bit ON
ScreenAOX 1,1,25,8O,&hF7FF, O, O 'set bold bit OFF
SUBROUTINE: ScreenBlink Row1%,Column1%,Row2%,Column2%,BlinkState%
Changes the blink bit for each character within the screen "box"
(upper-left=Row1%,Column1% lower-right=Row2%,Column2%) according to the
BlinkState%. If BlinkState% is zero then blink is turned OFF, otherwise
blink is turned ON. For example:
ScreenBlink 1,1,25,8O,1 'turn blink ON for entire screen
ScreenBlink 1,1,25,8O,O 'turn blink OFF for entire screen
SUBROUTINE: ScreenBold Row1%,Column1%,Row2%,Column2%,BoldState%
Changes the bold bit for each character within the screen "box"
(upper-left=Row1%,Column1% lower-right=Row2%,Column2%) according to the
BoldState%. If BoldState% is zero then bold is turned OFF, otherwise
bold is turned ON. For example:
ScreenBold 1,1,25,8O,1 'turn bold ON for entire screen
ScreenBold 1,1,25,8O,O 'turn bold OFF for entire screen
SUBROUTINE: ScreenBox Row1%,Column1%,Row2%,Column2%,BoxType%,ColorAttrib%
Draws a 'box' on a text-mode screen using the specified ColorAttrib%
(color-attribute-byte) value. The upper-left corner of the box is specified
by Row1%, Column1% and the lower-right corner is specified by Row2%, Column2%.
The BoxType% value specifies the type of box to draw (1OO to 1O4). Note that
the inside of the box is filled with spaces in the specified color.
┌───┐ ╒═══╕ ╓───╖ ╔═══╗ █▀▀▀█ Numbers outside the range of 1OO to 1O4
│1OO│ │1O1│ ║1O2║ ║1O3║ ▌1O4▐ will cause the ASCII character to be used
└───┘ ╘═══╛ ╙───╜ ╚═══╝ █▄▄▄█ as the border of the box. (e.g. 32=space)
example: ScreenBox 1,1,25,8O,1OO,3O
'draw a single-line box covering the entire screen
'(upper-left row,col=1,1 to lower-right row,col=25,8O) ┌──yellow ┌──blue
'using yellow foreground on blue background 3O = ( 14 + ( 16 * ( 1 ) )
SUBROUTINE: ScreenFade Fade%,MemSeg%
Transfers the 4OOO-byte text screen image stored at memory location MemSeg%:OOOO
to the screen using the specified Fade%. (see the Fade Table in the Appendix).
Note that the screen image must be stored at offset OOOO within the given
segment (MemSeg%). This can be done by using the MemCopy command and others.
example: ScreenFade 255,&h1234
'copy 4OOO-byte image at 1234:OOOO to the screen using random Fade%=255
'Note: The current version of this routine passes parameters by value (BYVAL).
SUBROUTINE: ScreenFill Row1%,Column1%,Row2%,Column2%,ASCIIChar%,ColorAttr%
Fills the screen "box" (upper-left=Row1%,Column1% lower-right=Row2%,Column2%)
with the specified ASCIIChar% and ColorAttr%. If ASCIIChar% is -1 then
characters remain unaltered. If ColorAttr% is -1 then color attributes remain
unaltered. For example: (ASCII 32=space ATTR 3O is yellow/blue)
ScreenFill 1,1,25,8O,32,3O 'fill screen with spaces in yellow/blue colors
ScreenFill 1,1,25,8O,32,-1 'fill screen with spaces (colors unchanged)
ScreenFill 1,1,25,8O,-1,3O 'fill screen in yellow/blue colors (ASCII unchanged)
FUNCTION: ScreenLoad% (FileName$)
Loads the 4OOO-byte text screen image file from the specified FileName$ to
the screen. The function returns -1 if any file errors occur, otherwise it
returns O. Note that this function can also load 4OO7-byte BSAVE files.
example: ErrCode% = ScreenLoad%("TEST.SCN") 'load file to screen
SUBROUTINE: ScreenMarquee Row1%,Column1%,Row2%,Column2%,Attr%
Places a "marquee" (i.e. flashing box) around the specified screen coordinates.
The upper-left corner is defined by (Row1%,Column1%) and the lower-right corner
is defined by (Row2%,Column2%). The marquee colors are specified by the Attr%
color-attribute-byte operand. Note that only low-intensity foreground and
background colors are used. The area, inside the box, is not altered.
example: ScreenMarquee 1,1,25,8O,83
'draw a marquee around the entire screen
'(upper-left row,col=1,1 to lower-right row,col=25,8O) ┌─cyan ┌─magenta
'using cyan and magenta 83 = ( 3 + ( 16 * ( 5 ) )
SUBROUTINE: ScreenPrint
Prints the current screen (same as pressing the Shift+Print-Screen key).
example: ScreenPrint
---or---
Call ScreenPrint
FUNCTION: ScreenSave% (FileName$)
Saves the current text mode screen to the specified FileName$. The file size
is always 4OOO bytes. The function returns -1 if any file errors occur,
otherwise it returns O.
example: ErrCode% = ScreenSave%("TEST.SCN") 'save screen to file
SUBROUTINE: ScreenScroll Numlines%,Row1%,Column1%,Row2%,Column2%,Attribute%
Causes the screen to scroll (up if NumLines% is positive, down if NumLines% is
negative) by the specified number of lines (NumLines%). The portion of the
screen to be scrolled is determined by the upper-left corner (Row1%,Column1%)
and the lower-right corner (Row2%,column2%). The lines which are left vacant
by the scrolling process are filled in with spaces in the color specified by
Attribute% (color-attribute-byte format).
example: ScreenScroll (-5,1,1,25,8O,3O)
'scroll-down entire screen by 5 lines - fill in with spaces (yellow on blue)
SUBROUTINE: ScreenString Text$,Row%,Column%,NumBytes%
Copies the specified number of bytes (NumBytes%) of text from the screen
(at Row%,Column%) to a variable-length string variable (e.g. Text$). Note that
only text is copied. The color attributes are ignored.
example: Locate 12,4O : Print "The quick brown fox jumps over the lazy dog"
ScreenString Text$,12,5O,9 'means Text$ will contain "brown fox"
FUNCTION: ScreenTicker%(Message$,Row%,StartColumn%,EndColumn%,ColorAttrib%,_
ExitKey%,Speed%)
Places a 'ticker-tape' message on the screen on Row% between StartColumn% and
EndColumn% (inclusive). Message$ contains the text to be displayed and can be
longer than the message box area on the screen. The ColorAttrib% operand
(in color-attribute-byte format) specifies the screen colors to be used for
the message box. The Speed% operand specifies the time delay between character
movement and should be between (1=fast and 1O=slow). The ExitKey% operand
specifies what key will cause the 'ticker-tape' message to terminate (O=any
key). The key-code values are listed in the appendix. The message-box-area
of the screen is restored to its previous state when the function ends. The
return value of this function (ScreenTicker%) is the key-code of the key used
to terminate this function (same as ExitKey% except when ExitKey%=O (any key)
is used).
FUNCTION: ScreenToMem% (MemSeg%,MemPtr%,Row1%,Column1%,Row2%,Column2%)
FUNCTION: MemToScreen% (MemSeg%,MemPtr%,Row%,Column%)
These two functions allow a "box" of ASCII color text on the screen to be
stored-to/restored-from memory.
To store a block of text:
A%=ScreenToMem%(MemSeg%,MemPtr%,Row1%,Column1%,Row2%,Column2%)
This command will store the block of text (upper-left corner=Row1%,Column1%
and lower-right corner=Row2%,Column2%) to memory starting at MemSeg%:MemPtr%.
The return value ScreenToMem% contains the number of bytes needed to store
that block. The "box" is stored as follows: a 2-byte video offset, then
1-byte for number of rows, then 1-byte for number of columns, then 2 bytes
for each character inside the "box".
To restore a block of text:
A%=MemToScreen%(MemSeg%,MemPtr%,Row%,Column%)
This command will restore the block "box" (previously stored at
MemSeg%:MemPtr%) to the screen coordinates Row%,Column%. If Row% is
specified as zero, then the "box" is placed at the same position on the
screen where it came from. Make sure the "box" will fit on the screen where
you place it. The return value is the number of bytes used to restore it.
Note: rows=1 to 25 and columns=1 to 8O.
SUBROUTINE: SetColorPDQ Attribute%
Sets the color-attribute-byte to the specified Attribute% for a program LINKed
with the PDQ libraries from Crescent Software. (see also ColorPDQ% function)
example: SetColorPDQ 3O 'sets color yellow on blue
** Use only if LINKed with PDQ libraries
** Will not work inside QB editor/environment or with Quick-BASIC libraries
SUBROUTINE: SetColorQB Attribute%
Sets the color-attribute-byte to the specified Attribute% for a program LINKed
with the standard Quick-BASIC libraries (BCOM45.LIB and QB.LIB).
example: SetColorQB 3O 'sets color yellow on blue (see also ColorQB% function)
** Use only if LINKed with Quick-BASIC libraries
** Will not work inside QB editor/environment or with PDQ libraries
SUBROUTINE: SetTextMode
Changes the screen mode to 8Ox25 text mode. (BIOS mode: 3=color 7=mono)
example: Call SetTextMode
SUBROUTINE: SetVideoSeg NewVideoSeg%
The SetVideoSeg subroutine sets the video segment for using virtual screens
with all of the GPS library screen functions. This routine sets the value
that is to be returned by the VideoSeg% function.
example: SetVideoSeg O 'resets the video segment to the REAL video segment
'MONO systems=&hBOOO (or -2O48O) COLOR systems=&hB8OO (or -18432)
SetVideoSeg &h7OOO 'sets video segment for virtual screens to &h7OOO
SUBROUTINE: SetVideoSegPDQ NewVideoSeg%
same as SetVideoSeg except that it sets the virtual video segment for programs
linked with PDQ. This routine sets the value that is returned by VideoSegPDQ%.
Note: This routine also updates the GPS library function VideoSeg%.
example: SetVideoSegPDQ O 'resets the video segment to the REAL video segment
'MONO systems=&hBOOO (or -2O48O) COLOR systems=&hB8OO (or -18432)
SetVideoSegPDQ &h7OOO 'sets video segment for virtual screens to &h7OOO
** Use only if LINKed with PDQ libraries
** Will not work inside QB editor/environment or with Quick-BASIC libraries
SUBROUTINE: SetVideoSegQB NewVideoSeg%
same as SetVideoSeg except that it sets the virtual video segment for programs
linked with QB. It affects only LOCATE and PRINT (CLS uses a BIOS call). This
routine sets the value that is returned by VideoSegQB%.
Note: This routine also updates the GPS library function VideoSeg%.
example: SetVideoSegQB O 'resets the video segment to the REAL video segment
'MONO systems=&hBOOO (or -2O48O) COLOR systems=&hB8OO (or -18432)
SetVideoSegQB &h7OOO 'sets video segment for virtual screens to &h7OOO
** Use only if LINKed with Quick-BASIC libraries
** Will not work inside QB editor/environment or with PDQ libraries
FUNCTION: VideoPtr% (Row%, Column%)
Returns the pointer (offset) in video memory where Row%,Column% is located.
It is useful whenever you wish to work directly with text-mode video memory.
example: A% = VideoPtr%(12,4O) 'A% would be 1838
'same as A% = ( ( Row% - 1 ) * 16O ) + ( ( Column% - 1 ) * 2 )
FUNCTION: VideoSeg%
The VideoSeg% function returns the current video memory segment for use with
GPS library screen functions.
example: VSeg% = VideoSeg% : DEF SEG=VSeg% : X% = PEEK(&hO5OO)
'see the SetVideoSeg subroutine
FUNCTION: VideoSegPDQ%
The VideoSeg% function returns the current video memory segment for use with
PDQ library screen functions.
example: VSegPDQ% = VideoSegPDQ% : DEF SEG=VSegPDQ% : X% = PEEK(&hO5OO)
'see the SetVideoSegPDQ subroutine
** Use only if LINKed with PDQ libraries
** Will not work inside QB editor/environment or with Quick-BASIC libraries
FUNCTION: VideoSegQB%
The VideoSeg% function returns the current video memory segment for use with
Quick-BASIC's screen functions (LOCATE and PRINT).
example: VSegQB% = VideoSegQB% : DEF SEG=VSegQB% : X% = PEEK(&hO5OO)
'see the SetVideoSegQB subroutine
** Use only if LINKed with Quick-BASIC libraries
** Will not work inside QB editor/environment or with PDQ libraries
┌─────────────────────────────────────────────────────────────────────────────┐
│ STRING FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
Note: Do NOT use fixed-length strings with these functions !!!
FUNCTION: AddCRLF$ (Text$)
Returns the specified string with a <carriage-return><line-feed> combination
appended to the end of it.
example: X$=AddCRLF$(Y$) 'would be the same as X$=Y$+CHR$(13)+CHR$(1O)
FUNCTION: AppLink$
Returns a 16-byte string containing the contents of the intra-application area
which is located at OOOO:O4FO in the BIOS data area of low memory. This area
can be used to hold data between CHAINed programs etc. (see SetAppLink)
example: SetApplink "This is a test"
A$=AppLink$ 'this would retrieve the string "This is a test "
FUNCTION: AscMid% (Text$, Position%)
Returns the ASCII value of the character located at Position% in the string
Text$. This function performs the same task as ASC(MID$(Text$,Position%)) but
it is faster.
example: A% = AscMid%("ABCDEFGH",4) 'A% would be equal to 68 (ASCII value of D)
FUNCTION: Bin$ (IntVal%)
Returns a 16-byte string representing the unsigned binary value of IntVal%.
example: A$=Bin$(&h1234)
'A$ would be "OOO1OO1OOO11O1OO" actual zeros are used (not letter O)
' └──┤└──┤└──┤└──┤
' 1 2 3 4 hexadecimal
'The Replace subroutine could now be used to convert all zeros in A$ to
'the letter O in order to enhance readability.
Replace A$,48,79 'replace all zeros (ASCII=48) with letter O (ASCII=79)
FUNCTION: Center$ (Text$, LineWidth%)
This function returns a string that is (LineWidth%) characters in length with
Text$ centered inside it. Leading and/or trailing spaces are used to pad the
string to the appropriate length. If Text$ is longer than LineWidth%, it is
truncated to fit.
example: A$=Center$("ABCD",7) 'A$ would be " ABCD "
A$=Center$("ABCDE",7) 'A$ would be " ABCDE "
A$=Center$("ABCDEF",7) 'A$ would be "ABCDEF "
A$=Center$("ABCDEFG",7) 'A$ would be "ABCDEFG"
FUNCTION: ChainLink$
Returns a 96-byte string containing the contents of the unused 96-byte area
at the end of text-mode video memory which is located at VideoSeg%:OFAO.
This area can be used to hold data between CHAINed programs etc. Note that
this function must not be used in text modes utilizing more than 8O columns
and 25 lines (such as 132 column modes or 43/5O/66 line modes).
(see SetChainLink)
example: SetChainlink "This is a test"
A$=ChainLink$ 'this would retrieve a 96-byte string
SUBROUTINE: ChgCase Text$
Changes the case of every alphabetic character in the Text$ string (i.e.
lower-case becomes upper-case and upper-case becomes lower-case).
example: Temp$="A-b-C-d-E-f"
ChgCase Temp$ 'Temp$ would be changed to "a-B-c-D-e-F"
NOTE: The string Text$ is changed (in place) and therefore MUST be a string
variable !!! It can NOT be a literal string ("x") or a string function
resultant (such as X$+Y$) !!!
SUBROUTINE: ChgMid Text$, Position%, NewValue%
Changes the ASCII value of the character at Position% in the string Text$ to
the ASCII value specified by NewValue%.
example: Text$="ABCDEFG"
ChgMid Text$,3,32 'Text$ would be changed to "AB DEFG"
NOTE: The string Text$ is changed (in place) and therefore MUST be a string
variable !!! It can NOT be a literal string ("x") or a string function
resultant (such as X$+Y$) !!!
FUNCTION: InstrFwd% (StartAt%, SearchIn$, LookFor$)
Returns the position of the first occurrence of LookFor$ in SearchIn$. The
forward order search begins at position StartAt%. This function is identical
to INSTR(StartAt%,SearchIn$,LookFor$) except that it returns zero if the
LookFor$ string is null. (BASIC's INSTR function returns 1 - Why ? Who Knows ?)
example: A%=INSTR (1,"ABC","") 'A%=1
A%=InstrFwd%(1,"ABC","") 'A%=O different from BASIC's INSTR
A%=InstrFwd%(1,"ABC","B") 'A%=2 same as BASIC's INSTR
FUNCTION: InstrRev% (StartAt%, SearchIn$, LookFor$)
Returns the position of the LAST occurrence of LookFor$ in SearchIn$.
The REVERSE-ORDER search begins at position StartAt%. If LookFor$ is null or
if StartAt% is zero, the function returns zero. If StartAt% is negative or if
StartAt% is greater than the length of SearchIn$, then StartAt% is set to the
length of SearchIn$.
example: 'separate the path from the filename
PF$="C:\TEMP\MISC\ABC.DAT" 'path+file (assume we don't know form yet)
X%=Larger%(InstrRev%(-1,PF$,"\"),InstrRev%(-1,PF$,":"))
P$=LEFT$(PF$,X%) 'Here's the path
F$=MID$(PF$,X%+1) 'and here's the filename
FUNCTION: IntStr$ (IntVal%)
Returns a forward-order 2-byte string from the 2-byte integer value IntVal%.
This string can then be used in a FIELD or PUT statement etc. The
forward-order means that the string can be sorted (unlike Quick-BASIC's
MKI$ function).
example: A$=IntStr$(&h1234)
FUNCTION: IStr$ (IntVal%)
Returns a string representation of the integer value (IntVal%) except that
there is no leading space. It is exactly the same as LTRIM$(STR$(IntVal%)).
FUNCTION: LJustify$ (Text$, LineWidth%)
This function returns a string that is (LineWidth%) characters in length with
Text$ left-justified inside it. Trailing spaces are used to pad the string to
the appropriate length. If Text$ is longer than LineWidth%, it is truncated.
example: A$=LJustify$("ABCD",5) 'A$ would be "ABCD "
A$=LJustify$("ABCDEFG",5) 'A$ would be "ABCDE"
FUNCTION: LongStr$ (LongVal&)
Returns a forward-order 4-byte string from the 4-byte (long) integer value
LongVal&. This string can then be used in a FIELD or PUT statement etc. The
forward-order means that the string can be sorted (unlike Quick-BASIC's
MKL$ function).
example: A$=LongStr$(&h12345678)
SUBROUTINE: LowerCase Text$
Changes any upper-case characters in Text$ to their lower-case equivalents.
example: Text$="AbCdEf"
LowerCase Text$ 'Text$ would be "abcdef"
NOTE: The string Text$ is changed (in place) and therefore MUST be a string
variable !!! It can NOT be a literal string ("x") or a string function
resultant (such as X$+Y$) !!!
FUNCTION: LStr$ (LongVal&)
Returns a string representation of the long integer value (LongVal&) except that
there is no leading space. It is exactly the same as LTRIM$(STR$(LongVal&)).
SUBROUTINE: MemToString Text$,MemSeg%,MemPtr%,NumBytes%
Copies a block of memory starting at MemSeg%:MemPtr% and having a length (in
bytes) of NumBytes% into a variable-length string variable (e.g. Text$).
example: MemToString Text$,&hB8OO,O,4OOO 'copy color screen to Text$
'note: DGROUP string area is small so
' you should use sparingly.
'see also: StringToMem subroutine
FUNCTION: NoMid$ (Text$, StartPos%, NumChars%)
Returns the Text$ string with a section removed from it. The section that is
removed begins at StartPos% and is NumChars% characters long. Essentially
this function discards what BASIC's MID$ function keeps and vice versa.
example: A$= MID$("ABCDEFGHIJK",4,3) 'A$ would be "DEF"
A$=NoMid$("ABCDEFGHIJK",4,3) 'A$ would be "ABCGHIJK"
FUNCTION: NoSegm$ (Text$, StartPos%, EndPos%)
Returns the Text$ string with a section removed from it. The section that is
removed begins at StartPos% and continues to EndPos%.
example: A$=NoSegm$("ABCDEFGHIJK",3,7) 'A$ would be "ABHIJK"
FUNCTION: NoSpace$ (Text$)
Returns a string (from Text$) containing no imbedded spaces or nulls.
example: A$=NoSpace$(" Testing 1 2 3 ") 'A$ would be "Testing123"
FUNCTION: Repeat$ (Text$, NumTimes%)
Returns a string containing Text$ repeated (NumTimes%) number of times.
example: A$=Repeat$("Testing",3) 'A$ would be "TestingTestingTesting"
SUBROUTINE: Replace Text$, OldChar%, NewChar%
Converts all characters, having an ASCII value of OldChar%, in Text$ to the
new ASCII value of NewChar%.
example: Text$="This is a test"
Replace Text$,32,45 'Text$ would be "This-is-a-test"
space─┘ └─dash
NOTE: The string Text$ is changed (in place) and therefore MUST be a string
variable !!! It can NOT be a literal string ("x") or a string function
resultant (such as X$+Y$) !!!
FUNCTION: Reverse$ (Text$)
Returns a string containing Text$ in reverse order.
example: A$=Reverse$("ABCD") 'A$ would be "DCBA"
FUNCTION: RJustify$ (Text$, LineWidth%)
This function returns a string that is (LineWidth%) characters in length with
Text$ right-justified inside it. Leading spaces are used to pad the string to
the appropriate length. If Text$ is longer than LineWidth%, it is truncated.
Note: If truncation is necessary, the RIGHT-most characters are preserved.
example: A$=RJustify$("ABCD",5) 'A$ would be " ABCD"
A$=RJustify$("ABCDEFG",5) 'A$ would be "CDEFG"
FUNCTION: Segm$ (Text$, StartPos%, EndPos%)
Returns the portion of Text$ which starts at StartPos% and ends at EndPos%.
example: A$=Segm$("ABCDEFGHIJK",5,7) 'A$ would be "EFG"
SUBROUTINE: SetChainLink Link$
Sets the contents of the unused 96-byte area at the end of text-mode video
memory equal to the string value Link$. This area can be used to hold data
between CHAINed programs etc. Note that this function must not be used in
text modes utilizing more than 8O columns and 25 lines (such as 132 column modes
or 43/5O/66 line modes). The area is padded with spaces to the right if Link$
is less than 96 bytes in length. (see ChainLink$)
example: SetChainlink "This is a test"
A$=ChainLink$ 'this would retrieve a 96-byte string
SUBROUTINE: SetAppLink App$
Sets the contents of the 16-byte intra-application area equal to the specified
string value App$. This area can hold data between CHAINed programs. Note
that the area is padded with spaces to the right if App$ is less than 16 bytes
in length. (see AppLink$)
example: SetApplink "This is a test"
A$=AppLink$ 'this would retrieve the string "This is a test "
FUNCTION: StrChkSum& (Text$)
Returns a long integer value representing the sum of all the bytes (ASCII
values) in the Text$ string.
example: A&=StrChkSum&("ABC") 'A& would be 198=65+66+67
SUBROUTINE: StringToMem Text$,MemSeg%,MemPtr%,NumBytes%
Copies a variable-length string (e.g. Text$) into a block of memory starting at
MemSeg%:MemPtr% and having a length (in bytes) of NumBytes%.
example: StringToMem Text$,&hB8OO,O,4OOO
'copy Text$ to color screen
'note: DGROUP string area is small so you should use sparingly.
' If length of Text$ is larger than NumBytes%, then copying
' is stopped at count=NumBytes%. If length of Text$ is
' smaller than NumBytes%, spaces are used to pad additional memory
'see also: MemToString subroutine
FUNCTION: StrInt% ( IntVal$ )
Returns a 2-byte integer value from the 2-byte string value IntVal$. Note
that IntVal$ must have been made by the IntStr$ function because the StrInt%
function requires a forward-order string operand. (see IntStr$)
example: A$=IntStr$(1234%)
A%=StrInt%(A$) 'A% would be 1234
FUNCTION: StrLong& ( IntVal$ )
Returns a 4-byte (long) integer value from the 4-byte string value IntVal$.
Note that IntVal$ must have been made by the LongStr$ function because the
StrLong& function requires a forward-order string operand. (see LongStr$)
example: A$=LongStr$(123456789&)
A&=StrLong(A$) 'A& would be 123456789
FUNCTION: Trim$ (Text$)
Trims spaces from the left and right ends of Text$. It is the same as using
RTRIM$(LTRIM$(Text$)).
FUNCTION: TrimLCase$ (Text$)
Trims spaces from the left and right ends of Text$ and also converts all
alphabetic characters to lower case. It is the same as using
LCASE$(RTRIM$(LTRIM$(Text$))).
FUNCTION: TrimUCase$ (Text$)
Trims spaces from the left and right ends of Text$ and also converts all
alphabetic characters to upper case. It is the same as using
UCASE$(RTRIM$(LTRIM$(Text$))).
SUBROUTINE: UpperCase Text$
Changes any lower-case characters in Text$ to their upper-case equivalents.
example: Text$="AbCdEf"
UpperCase Text$ 'Text$ would be "ABCDEF"
NOTE: The string Text$ is changed (in place) and therefore MUST be a string
variable !!! It can NOT be a literal string ("x") or a string function
resultant (such as X$+Y$) !!!
SUBROUTINE: XORString Text$, XORValue%
Performs the eXclusive-OR function (using XORValue%) on each character in the
string value Text$. This makes it possible to implement a very simple
encryption system.
example: Text$="@@@" : XORString Text$,1 'Text$ would be changed to "AAA"
XORString Text$,1 'Text$ would be changed back to "@@@"
NOTE: The string Text$ is changed (in place) and therefore MUST be a string
variable !!! It can NOT be a literal string ("x") or a string function
resultant (such as X$+Y$) !!!
┌─────────────────────────────────────────────────────────────────────────────┐
│ SYSTEM / MISCELLANEOUS FUNCTIONS │
└─────────────────────────────────────────────────────────────────────────────┘
SUBROUTINE: ColdBoot
Performs a COLD boot on the PC like pressing the Reset button. (checks memory)
example: ColdBoot
--or--
Call ColdBoot
FUNCTION: DOSVersion%
Returns the version of DOS currently in use on the PC (multiplied by 1OO).
example: DV%=DOSVersion%
'if DOS version is 3.31 then DV%=331
'if DOS version is 5.OO then DV%=5OO
SUBROUTINE: FormFeed
Sends a form-feed (ascii 12) to the printer (PRN device usually LPT1:).
example: FormFeed
--or--
Call FormFeed
SUBROUTINE: WarmBoot
Performs a WARM boot on the PC like typing Ctrl-Alt-Del. (no memory check)
example: WarmBoot
--or--
Call WarmBoot
APPENDIX A - KEYCODE VALUES RETURNED BY THE KEYBOARD FUNCTIONS
(1O1-Key Keyboard)
Note: The special function keys return (negative of scan_code)
┌─────┬─────┬─────┬─────┐ ┌─────┬─────┬─────┬─────┐
key │ │SHIFT│ CTRL│ ALT │ key │ │SHIFT│ CTRL│ ALT │
┌───────┼─────┼─────┼─────┼─────┤ ┌───────┼─────┼─────┼─────┼─────┤
│ A │* 97 │ 65 │ 1 │ -3O │ │ ESC │ 27 │ 27 │ 27 │ ∙ │
│ B │ 98 │ 66 │ 2 │ -48 │ │ BKSP │ 8 │ 8 │ 127 │ ∙ │
│ C │ 99 │ 67 │ 3 │ -46 │ │ TAB │ 9 │ -15 │ ∙ │ ∙ │
│ D │ 1OO │ 68 │ 4 │ -32 │ │ SPACE │ 32 │ 32 │ 32 │ 32 │
│ E │ 1O1 │ 69 │ 5 │ -18 │ │ ENTER │ 13 │ 13 │ 1O │ ∙ │
│ F │ 1O2 │ 7O │ 6 │ -33 │ │ F1 │ -59 │ -84 │ -94 │-1O4 │
│ G │ 1O3 │ 71 │ 7 │ -34 │ │ F2 │ -6O │ -85 │ -95 │-1O5 │
│ H │ 1O4 │ 72 │ 8 │ -35 │ │ F3 │ -61 │ -86 │ -96 │-1O6 │
│ I │ 1O5 │ 73 │ 9 │ -23 │ │ F4 │ -62 │ -87 │ -97 │-1O7 │
│ J │ 1O6 │ 74 │ 1O │ -36 │ │ F5 │ -63 │ -88 │ -98 │-1O8 │
│ K │ 1O7 │ 75 │ 11 │ -37 │ │ F6 │ -64 │ -89 │ -99 │-1O9 │
│ L │ 1O8 │ 76 │ 12 │ -38 │ │ F7 │ -65 │ -9O │-1OO │-11O │
│ M │ 1O9 │ 77 │ 13 │ -5O │ │ F8 │ -66 │ -91 │-1O1 │-111 │
│ N │ 11O │ 78 │ 14 │ -49 │ │ F9 │ -67 │ -92 │-1O2 │-112 │
│ O │ 111 │ 79 │ 15 │ -24 │ │ F1O │ -68 │ -93 │-1O3 │-113 │
│ P │ 112 │ 8O │ 16 │ -25 │ │ F11 │ ∙ │ ∙ │ ∙ │ ∙ │
│ Q │ 113 │ 81 │ 17 │ -16 │ │ F12 │ ∙ │ ∙ │ ∙ │ ∙ │
│ R │ 114 │ 82 │ 18 │ -19 │ │ UP │ -72 │ -72 │ ∙ │ ∙ │
│ S │ 115 │ 83 │ 19 │ -31 │ │ DOWN │ -8O │ -8O │ ∙ │ ∙ │
│ T │ 116 │ 84 │ 2O │ -2O │ │ LEFT │ -75 │ -75 │-115 │ ∙ │
│ U │ 117 │ 85 │ 21 │ -22 │ │ RIGHT │ -77 │ -77 │-116 │ ∙ │
│ V │ 118 │ 86 │ 22 │ -47 │ │ INS │ -82 │ -82 │ ∙ │ ∙ │
│ W │ 119 │ 87 │ 23 │ -17 │ │ DEL │ -83 │ -83 │ ∙ │ ∙ │
│ X │ 12O │ 88 │ 24 │ -45 │ │ HOME │ -71 │ -71 │-119 │ ∙ │
│ Y │ 121 │ 89 │ 25 │ -21 │ │ END │ -79 │ -79 │-117 │ ∙ │
│ Z │ 122 │ 9O │ 26 │ -44 │ │ PGUP │ -73 │ -73 │ 1O1 │ ∙ │
│ O or )│ 48 │ 41 │ ∙ │-129 │ │ PGDN │ -81 │ -81 │-118 │ ∙ │
│ 1 or !│ 49 │ 33 │ ∙ │-12O │ │ - or _│ 45 │ 95 │ 31 │-13O │
│ 2 or @│ 5O │ 64 │ -3 │-121 │ │ + or =│ 61 │ 43 │ ∙ │-131 │
│ 3 or #│ 51 │ 35 │ ∙ │-122 │ │ | or \│ 92 │ 124 │ 28 │ ∙ │
│ 4 or $│ 52 │ 36 │ ∙ │-123 │ │ { or [│ 91 │ 123 │ 27 │ ∙ │
│ 5 or %│ 53 │ 37 │ ∙ │-124 │ │ ] or }│ 93 │ 125 │ 29 │ ∙ │
│ 6 or ^│ 54 │ 94 │ 3O │-125 │ │ : or ;│ 59 │ 58 │ ∙ │ ∙ │
│ 7 or &│ 55 │ 38 │ ∙ │-126 │ │ " or '│ 39 │ 34 │ ∙ │ ∙ │
│ 8 or *│ 56 │ 42 │ ∙ │-127 │ │ < or ,│ 44 │ 6O │ ∙ │ ∙ │
│ 9 or (│ 57 │ 4O │ ∙ │-128 │ │ > or .│ 46 │ 62 │ ∙ │ ∙ │
│ ` or ~│ 96 │ 126 │ ∙ │ ∙ │ │ ? or /│ 47 │ 63 │ ∙ │ ∙ │
└───────┴─────┴─────┴─────┴─────┘ └───────┴─────┴─────┴─────┴─────┘
* indicates keycode for lower-case alphabetic characters
for example: a=97 A=65
z=122 Z=9O
┌──────────────────────────────────────────────────────────────────────────────┐
│ APPENDIX B FADES for the ScreenFade Subroutine │
├──────────────────┬┬──────────────────┬┬──────────────────┬┬──────────────────┤
│ O Quick ││19 Spiral CW In ││38 Wipe V Close ││57 Circ Sweep Down│
│ 1 Fizz ││2O Spiral CW Out ││39 Half Wipe V U/D││58 Circ Sweep Up │
│ 2 Melt Down ││21 Spiral CCW In ││4O Half Wipe V D/U││59 Radar CW │
│ 3 Melt Up ││22 Spiral CCW Out ││41 Half Wipe H L/R││6O Radar CCW │
│ 4 Liquid Flow Dn ││23 Mult Sp CW In ││42 Half Wipe H R/L││61 Louver H Large │
│ 5 Liquid Flow Up ││24 Mult Sp CW Out ││43 Checker Down ││62 Louver H Small │
│ 6 Quarters - CW ││25 Mult Sp CCW In ││44 Checker Up ││63 Louver V Large │
│ 7 Quarters - CCW ││26 Mult Sp CCW Out││45 Diagonal Right ││64 Louver V Small │
│ 8 Quarters - Alt ││27 Wipe Down ││46 Diagonal Left ││ │
│ 9 Blks Random Lg ││28 Wipe Up ││47 Chckr Lvr 1step││ │
│1O Blks Random Sm ││29 Wipe Right ││48 Chckr Lvr 2step││ │
│11 Zigzag H Lg Rt ││3O Wipe Left ││49 Diagonal Lvr R ││ │
│12 Zigzag H Lg Lft││31 Curtain H Open ││5O Diagonal Lvr L ││ │
│13 Zigzag H Sm Rt ││32 Curtain H Close││51 Page Feed Down ││ │
│14 Zigzag H Sm Lft││33 Curtain V Open ││52 Page Feed Up ││ │
│15 Zigzag V Down ││34 Curtain V Close││53 Page Feed Right││ │
│16 Zigzag V Up ││35 Wipe H Open ││54 Page Feed Left ││255 selects a │
│17 Orifice Open ││36 Wipe H Close ││55 Circ Sweep CW ││ random fade │
│18 Orifice Close ││37 Wipe V Open ││56 Circ Sweep CCW ││ from this list│
└──────────────────┴┴──────────────────┴┴──────────────────┴┴──────────────────┘
Note: The program FADES.EXE will demonstrate each of these fades.